Update Purchase
const options = {
method: 'PATCH',
headers: {
'x-api-key': '<x-api-key>',
'x-organization-id': '<x-organization-id>',
'Content-Type': '<content-type>'
},
body: JSON.stringify({
product_name: '<string>',
sector: '<string>',
quantity: 123,
unit_id: '<string>',
purchase_date: '<string>',
expense_type: '<string>',
description: '<string>',
purchase_type: '<string>',
status: '<string>',
recycled: 123,
supplier_id: '<string>',
custom_emission_factor_id: '<string>',
frequency: '<string>',
file_id: '<string>',
file_name: '<string>',
file_url: '<string>'
})
};
fetch('https://api.dcycle.io/v1/purchases/{purchase_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.dcycle.io/v1/purchases/{purchase_id}"
payload = {
"product_name": "<string>",
"sector": "<string>",
"quantity": 123,
"unit_id": "<string>",
"purchase_date": "<string>",
"expense_type": "<string>",
"description": "<string>",
"purchase_type": "<string>",
"status": "<string>",
"recycled": 123,
"supplier_id": "<string>",
"custom_emission_factor_id": "<string>",
"frequency": "<string>",
"file_id": "<string>",
"file_name": "<string>",
"file_url": "<string>"
}
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>",
"Content-Type": "<content-type>"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)curl --request PATCH \
--url https://api.dcycle.io/v1/purchases/{purchase_id} \
--header 'Content-Type: <content-type>' \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>' \
--data '
{
"product_name": "<string>",
"sector": "<string>",
"quantity": 123,
"unit_id": "<string>",
"purchase_date": "<string>",
"expense_type": "<string>",
"description": "<string>",
"purchase_type": "<string>",
"status": "<string>",
"recycled": 123,
"supplier_id": "<string>",
"custom_emission_factor_id": "<string>",
"frequency": "<string>",
"file_id": "<string>",
"file_name": "<string>",
"file_url": "<string>"
}
'{
"id": "<string>",
"organization_id": "<string>",
"product_name": {},
"description": {},
"sector": {},
"quantity": {},
"unit_id": {},
"purchase_date": {},
"purchase_type": {},
"expense_type": "<string>",
"status": {},
"recycled": {},
"supplier_id": {},
"custom_emission_factor_id": {},
"file_id": {},
"file_name": {},
"file_url": {},
"co2e": {},
"frequency": {},
"exchange_rate_to_eur": {},
"exchange_rate_date": {},
"custom_emission_group": {},
"last_purchase_timestamp": {},
"supplier": {},
"unit": {
"id": "<string>",
"name": "<string>",
"type": "<string>"
},
"uploaded_by": {},
"uploaded_by_user": {},
"created_at": {},
"updated_at": {}
}Update Purchase
Modify an existing purchase’s details
PATCH
/
v1
/
purchases
/
{purchase_id}
Update Purchase
const options = {
method: 'PATCH',
headers: {
'x-api-key': '<x-api-key>',
'x-organization-id': '<x-organization-id>',
'Content-Type': '<content-type>'
},
body: JSON.stringify({
product_name: '<string>',
sector: '<string>',
quantity: 123,
unit_id: '<string>',
purchase_date: '<string>',
expense_type: '<string>',
description: '<string>',
purchase_type: '<string>',
status: '<string>',
recycled: 123,
supplier_id: '<string>',
custom_emission_factor_id: '<string>',
frequency: '<string>',
file_id: '<string>',
file_name: '<string>',
file_url: '<string>'
})
};
fetch('https://api.dcycle.io/v1/purchases/{purchase_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.dcycle.io/v1/purchases/{purchase_id}"
payload = {
"product_name": "<string>",
"sector": "<string>",
"quantity": 123,
"unit_id": "<string>",
"purchase_date": "<string>",
"expense_type": "<string>",
"description": "<string>",
"purchase_type": "<string>",
"status": "<string>",
"recycled": 123,
"supplier_id": "<string>",
"custom_emission_factor_id": "<string>",
"frequency": "<string>",
"file_id": "<string>",
"file_name": "<string>",
"file_url": "<string>"
}
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>",
"Content-Type": "<content-type>"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)curl --request PATCH \
--url https://api.dcycle.io/v1/purchases/{purchase_id} \
--header 'Content-Type: <content-type>' \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>' \
--data '
{
"product_name": "<string>",
"sector": "<string>",
"quantity": 123,
"unit_id": "<string>",
"purchase_date": "<string>",
"expense_type": "<string>",
"description": "<string>",
"purchase_type": "<string>",
"status": "<string>",
"recycled": 123,
"supplier_id": "<string>",
"custom_emission_factor_id": "<string>",
"frequency": "<string>",
"file_id": "<string>",
"file_name": "<string>",
"file_url": "<string>"
}
'{
"id": "<string>",
"organization_id": "<string>",
"product_name": {},
"description": {},
"sector": {},
"quantity": {},
"unit_id": {},
"purchase_date": {},
"purchase_type": {},
"expense_type": "<string>",
"status": {},
"recycled": {},
"supplier_id": {},
"custom_emission_factor_id": {},
"file_id": {},
"file_name": {},
"file_url": {},
"co2e": {},
"frequency": {},
"exchange_rate_to_eur": {},
"exchange_rate_date": {},
"custom_emission_group": {},
"last_purchase_timestamp": {},
"supplier": {},
"unit": {
"id": "<string>",
"name": "<string>",
"type": "<string>"
},
"uploaded_by": {},
"uploaded_by_user": {},
"created_at": {},
"updated_at": {}
}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
Headers
string
required
Your API key for authenticationExample:
sk_live_1234567890abcdefstring
required
Your organization UUIDExample:
a8315ef3-dd50-43f8-b7ce-d839e68d51fastring
required
Must be
application/jsonPath Parameters
string
required
The unique identifier (UUID) of the purchase to updateExample:
550e8400-e29b-41d4-a716-446655440000Body Parameters
string
Name of the product or service purchased (max 255 characters)Example:
"Office Supplies - Updated"string
Economic sector for emission factor lookup (max 255 characters)Example:
"Retail trade"number
Purchase amount (must be >= 0). For spend-based, this is the monetary value.Example:
2000.00string
Unit of measurement (e.g., EUR, USD, kg)Example:
"EUR"string
Date of purchase in YYYY-MM-DD formatExample:
"2024-03-20"string
Expense classificationAvailable values:
capex, opexExample: "capex"string
Optional description of the purchase (max 500 characters)Example:
"Updated Q1 2024 order with additional items"string
Calculation method for emissionsAvailable values:
spend_based, supplier_specificExample: "supplier_specific"string
Purchase statusAvailable values:
active, pending, in_progress, in_review, inactiveExample: "in_review"number
Recycled content percentage (0 to 1). Reduces calculated emissions.Example:
0.5 (50% recycled content)string
Optional supplier identifier for referenceExample:
"supplier-456"string
UUID of custom emission factor for supplier-specific calculationsExample:
"770e8400-e29b-41d4-a716-446655440000"string
Purchase frequencyAvailable values:
onceExample: "once"string
UUID of linked file/documentExample:
"660e8400-e29b-41d4-a716-446655440000"string
Name of linked file (max 255 characters)Example:
"invoice_q1_2024_updated.pdf"string
URL of linked fileExample:
"https://storage.dcycle.io/..."Response
Returns the updated purchase object with recalculated emissions.string
Unique identifier (UUID)
string
Organization UUID
string | null
Name of the product or service
string | null
Optional description
string | null
Economic sector
number | null
Purchase amount
string | null
Unit of measurement
date | null
Date of purchase
string | null
Calculation method:
spend_based or supplier_specificstring
Classification:
capex or opexstring | null
Purchase status
number | null
Recycled content percentage (0-1)
string | null
Supplier identifier
string | null
Custom emission factor UUID
string | null
Linked file UUID
string | null
Linked file name
string | null
Linked file download URL
number | null
Recalculated CO2 equivalent emissions (kg)
string | null
Purchase frequency
number | null
Exchange rate used to convert the purchase amount to EUR
date | null
Date used for the exchange rate lookup
object | null
Custom emission group applied to this purchase
| Field | Type | Description |
|---|---|---|
id | string | Group UUID |
name | string | null | Group name |
category | string | null | Group category |
description | string | null | Group description |
datetime | null
Timestamp of the most recent purchase in a recurring series
object | null
Supplier details
| Field | Type | Description |
|---|---|---|
id | string | Supplier UUID |
business_name | string | null | Supplier business name |
country | string | null | Supplier country code |
enabled | boolean | null | Whether the supplier is enabled |
object | null
string | null
UUID of the user who created this record
object | null
User who created this record
| Field | Type | Description |
|---|---|---|
id | string | User UUID |
first_name | string | First name |
last_name | string | Last name |
email | string | Email address |
profile_img_url | string | null | Profile image URL |
datetime
Timestamp when the purchase was created
datetime | null
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"
}'
import requests
import os
api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")
purchase_id = "550e8400-e29b-41d4-a716-446655440000"
headers = {
"x-api-key": api_key,
"x-organization-id": org_id,
"Content-Type": "application/json"
}
# Only include fields to update
payload = {
"quantity": 2000.00,
"recycled": 0.5,
"description": "Updated order with additional items"
}
response = requests.patch(
f"https://api.dcycle.io/v1/purchases/{purchase_id}",
headers=headers,
json=payload
)
purchase = response.json()
print(f"Updated: {purchase['product_name']}")
print(f"New CO2e: {purchase['co2e']} kg")
const axios = require('axios');
const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;
const purchaseId = '550e8400-e29b-41d4-a716-446655440000';
const headers = {
'x-api-key': apiKey,
'x-organization-id': orgId,
'Content-Type': 'application/json'
};
// Only include fields to update
const payload = {
quantity: 2000.00,
recycled: 0.5,
description: 'Updated order with additional items'
};
axios.patch(
`https://api.dcycle.io/v1/purchases/${purchaseId}`,
payload,
{ headers }
)
.then(response => {
const purchase = response.data;
console.log(`Updated: ${purchase.product_name}`);
console.log(`New CO2e: ${purchase.co2e} kg`);
})
.catch(error => console.error(error));
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",
"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",
"exchange_rate_to_eur": 1.0,
"exchange_rate_date": "2024-03-15",
"custom_emission_group": null,
"last_purchase_timestamp": null,
"supplier": {
"id": "supplier-123",
"business_name": "Office Depot",
"country": "ES",
"enabled": true
},
"unit": { "id": "unit-uuid", "name": "EUR" },
"uploaded_by": null,
"uploaded_by_user": null,
"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"
}
]
}
recycledis between 0 and 1quantityis >= 0expense_typeis eithercapexoropexpurchase_typeis eitherspend_basedorsupplier_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'])}")
Related Endpoints
Get Purchase
View purchase details
Delete Purchase
Remove a purchase
List Purchases
View all purchases
Custom Emission Factors
Create supplier-specific factors
Was this page helpful?