Update Purchase
Update an existing purchase’s information. You can modify any combination of the purchase’s fields.
Partial Updates: Only include the fields you want to update. Fields not included in the request body will remain unchanged.
Request
Your API key for authenticationExample: sk_live_1234567890abcdef
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
Path Parameters
The unique identifier (UUID) of the purchase to updateExample: 550e8400-e29b-41d4-a716-446655440000
Body Parameters
Name of the product or service purchased (max 255 characters)Example: "Office Supplies - Updated"
Economic sector for emission factor lookup (max 255 characters)Example: "Retail trade"
2-letter ISO country code where the purchase was madeExample: "DE"
Purchase amount (must be >= 0). For spend-based, this is the monetary value.Example: 2000.00
Unit of measurement (e.g., EUR, USD, kg)Example: "EUR"
Date of purchase in YYYY-MM-DD formatExample: "2024-03-20"
Expense classificationAvailable values: capex, opexExample: "capex"
Optional description of the purchase (max 500 characters)Example: "Updated Q1 2024 order with additional items"
Calculation method for emissionsAvailable values: spend_based, supplier_specificExample: "supplier_specific"
Purchase statusAvailable values: active, pending, in_progress, in_review, inactiveExample: "in_review"
Recycled content percentage (0 to 1). Reduces calculated emissions.Example: 0.5 (50% recycled content)
Optional supplier identifier for referenceExample: "supplier-456"
custom_emission_factor_id
UUID of custom emission factor for supplier-specific calculationsExample: "770e8400-e29b-41d4-a716-446655440000"
Purchase frequencyAvailable values: onceExample: "once"
UUID of linked file/documentExample: "660e8400-e29b-41d4-a716-446655440000"
Name of linked file (max 255 characters)Example: "invoice_q1_2024_updated.pdf"
URL of linked fileExample: "https://storage.dcycle.io/..."
Response
Returns the updated purchase object with recalculated emissions.
Name of the product or service
2-letter ISO country code
Calculation method: spend_based or supplier_specific
Classification: capex or opex
Recycled content percentage (0-1)
custom_emission_factor_id
Custom emission factor UUID
Recalculated CO2 equivalent emissions (kg)
Timestamp when the purchase was created
Timestamp when the purchase was last updated
Example
curl -X PATCH "https://api.dcycle.io/v1/purchases/550e8400-e29b-41d4-a716-446655440000" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}" \
-H "Content-Type: application/json" \
-d '{
"quantity": 2000.00,
"recycled": 0.5,
"description": "Updated order with additional items"
}'
Successful Response
Status Code: 200 OK
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
"product_name": "Office Supplies",
"description": "Updated order with additional items",
"sector": "Manufacturing",
"country": "ES",
"quantity": 2000.00,
"unit_id": "EUR",
"purchase_date": "2024-03-15",
"purchase_type": "spend_based",
"expense_type": "opex",
"status": "active",
"recycled": 0.5,
"supplier_id": "supplier-123",
"custom_emission_factor_id": null,
"file_id": "660e8400-e29b-41d4-a716-446655440000",
"file_name": "invoice_q1_2024.pdf",
"file_url": "https://storage.dcycle.io/...",
"co2e": 163.7,
"frequency": "once",
"created_at": "2024-03-15T10:30:00Z",
"updated_at": "2024-03-20T14:45:00Z"
}
Common Errors
401 Unauthorized
Cause: Missing or invalid API key
{
"detail": "Invalid API key",
"code": "INVALID_API_KEY"
}
404 Not Found
Cause: Purchase not found or doesn’t belong to your organization
{
"detail": "Purchase not found",
"code": "PURCHASE_NOT_FOUND"
}
422 Validation Error
Cause: Invalid field values
{
"detail": [
{
"loc": ["body", "recycled"],
"msg": "ensure this value is less than or equal to 1",
"type": "value_error.number.not_le"
}
]
}
recycled is between 0 and 1quantity is >= 0country is a valid 2-letter ISO codeexpense_type is either capex or opexpurchase_type is either spend_based or supplier_specific
Use Cases
Update Quantity and Recalculate Emissions
Modify the purchase amount to update the calculated CO2e:
def update_purchase_quantity(purchase_id, new_quantity):
"""Update purchase quantity and recalculate emissions"""
response = requests.patch(
f"https://api.dcycle.io/v1/purchases/{purchase_id}",
headers=headers,
json={"quantity": new_quantity}
)
purchase = response.json()
print(f"New quantity: {purchase['quantity']} {purchase['unit_id']}")
print(f"New CO2e: {purchase['co2e']} kg")
return purchase
# Update purchase amount
purchase = update_purchase_quantity(
"550e8400-e29b-41d4-a716-446655440000",
3500.00
)
Change Calculation Method
Switch from spend-based to supplier-specific calculation:
def switch_to_supplier_specific(purchase_id, custom_factor_id):
"""Change purchase to use supplier-specific emission factor"""
response = requests.patch(
f"https://api.dcycle.io/v1/purchases/{purchase_id}",
headers=headers,
json={
"purchase_type": "supplier_specific",
"custom_emission_factor_id": custom_factor_id
}
)
return response.json()
# Switch to supplier-specific calculation
purchase = switch_to_supplier_specific(
"550e8400-e29b-41d4-a716-446655440000",
"770e8400-e29b-41d4-a716-446655440000"
)
print(f"New CO2e with supplier factor: {purchase['co2e']} kg")
Update Recycled Content
Adjust the recycled percentage for more accurate emissions:
def update_recycled_percentage(purchase_id, recycled_pct):
"""Update recycled content percentage (0 to 1)"""
response = requests.patch(
f"https://api.dcycle.io/v1/purchases/{purchase_id}",
headers=headers,
json={"recycled": recycled_pct}
)
return response.json()
# Set 30% recycled content
purchase = update_recycled_percentage(
"550e8400-e29b-41d4-a716-446655440000",
0.3
)
print(f"CO2e with recycled content: {purchase['co2e']} kg")
Mark Purchase as Inactive
Exclude a purchase from calculations:
def deactivate_purchase(purchase_id):
"""Mark purchase as inactive"""
response = requests.patch(
f"https://api.dcycle.io/v1/purchases/{purchase_id}",
headers=headers,
json={"status": "inactive"}
)
return response.json()
# Deactivate purchase
purchase = deactivate_purchase("550e8400-e29b-41d4-a716-446655440000")
print(f"{purchase['product_name']} is now {purchase['status']}")
Link Supporting Documentation
Attach an invoice or receipt to the purchase:
def link_document(purchase_id, file_id, file_name, file_url):
"""Link a document to a purchase"""
response = requests.patch(
f"https://api.dcycle.io/v1/purchases/{purchase_id}",
headers=headers,
json={
"file_id": file_id,
"file_name": file_name,
"file_url": file_url
}
)
return response.json()
# Link invoice
purchase = link_document(
"550e8400-e29b-41d4-a716-446655440000",
"660e8400-e29b-41d4-a716-446655440000",
"invoice_updated.pdf",
"https://storage.dcycle.io/..."
)
print(f"Linked document: {purchase['file_name']}")
Bulk Update Purchases
Update multiple purchases’ status:
def bulk_update_status(purchase_ids, new_status):
"""Update status for multiple purchases"""
results = {"success": [], "failed": []}
for purchase_id in purchase_ids:
try:
response = requests.patch(
f"https://api.dcycle.io/v1/purchases/{purchase_id}",
headers=headers,
json={"status": new_status}
)
if response.status_code == 200:
results["success"].append(purchase_id)
else:
results["failed"].append({"id": purchase_id, "error": response.text})
except Exception as e:
results["failed"].append({"id": purchase_id, "error": str(e)})
return results
# Mark purchases as reviewed
purchase_ids = [
"550e8400-e29b-41d4-a716-446655440000",
"550e8400-e29b-41d4-a716-446655440001"
]
results = bulk_update_status(purchase_ids, "active")
print(f"Updated: {len(results['success'])}")
print(f"Failed: {len(results['failed'])}")
