Skip to main content
PATCH
Update Purchase

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_1234567890abcdef
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
string
required
Must be application/json

Path Parameters

string
required
The unique identifier (UUID) of the purchase to updateExample: 550e8400-e29b-41d4-a716-446655440000

Body 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"
string
2-letter ISO country code where the purchase was madeExample: "DE"
number
Purchase amount (must be >= 0). For spend-based, this is the monetary value.Example: 2000.00
string
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
string | null
2-letter ISO country code
number | null
Purchase amount
string | null
Unit of measurement
date | null
Date of purchase
string | null
Calculation method: spend_based or supplier_specific
string
Classification: capex or opex
string | 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
datetime | null
Timestamp of the most recent purchase in a recurring series
object | null
Supplier details
object | null
Unit of measurement details
string | null
UUID of the user who created this record
object | null
User who created this record
datetime
Timestamp when the purchase was created
datetime | null
Timestamp when the purchase was last updated

Example

Successful Response

Status Code: 200 OK

Common Errors

401 Unauthorized

Cause: Missing or invalid API key
Solution: Verify your API key is valid and active.

404 Not Found

Cause: Purchase not found or doesn’t belong to your organization
Solution: Verify the purchase ID exists and belongs to the organization specified in the header.

422 Validation Error

Cause: Invalid field values
Solution: Check that:
  • recycled is between 0 and 1
  • quantity is >= 0
  • country is a valid 2-letter ISO code
  • expense_type is either capex or opex
  • purchase_type is either spend_based or supplier_specific

Use Cases

Update Quantity and Recalculate Emissions

Modify the purchase amount to update the calculated CO2e:

Change Calculation Method

Switch from spend-based to supplier-specific calculation:

Update Recycled Content

Adjust the recycled percentage for more accurate emissions:

Mark Purchase as Inactive

Exclude a purchase from calculations:
Attach an invoice or receipt to the purchase:

Bulk Update Purchases

Update multiple purchases’ status:

Get Purchase

View purchase details

Delete Purchase

Remove a purchase

List Purchases

View all purchases

Custom Emission Factors

Create supplier-specific factors