Get Purchase

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

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}"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/purchases/{purchase_id} \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "id": "<string>",
  "organization_id": "<string>",
  "product_name": {},
  "description": {},
  "sector": {},
  "country": {},
  "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": {},
  "uploaded_by": {},
  "uploaded_by_user": {},
  "created_at": {},
  "updated_at": {}
}

GET

purchases

{purchase_id}

Get Purchase

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

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}"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/purchases/{purchase_id} \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "id": "<string>",
  "organization_id": "<string>",
  "product_name": {},
  "description": {},
  "sector": {},
  "country": {},
  "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": {},
  "uploaded_by": {},
  "uploaded_by_user": {},
  "created_at": {},
  "updated_at": {}
}

Get Purchase

Retrieve detailed information about a specific purchase using its unique identifier.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

string

required

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

Response

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

Calculated 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

Unit of measurement details

Field	Type	Description
`id`	string	Unit UUID
`name`	string	Unit name (e.g. `EUR`, `kilogram_(kg)`)
`type`	string	Unit category

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 GET "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}"

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")

headers = {
    "x-api-key": api_key,
    "x-organization-id": org_id
}

purchase_id = "550e8400-e29b-41d4-a716-446655440000"

response = requests.get(
    f"https://api.dcycle.io/v1/purchases/{purchase_id}",
    headers=headers
)

purchase = response.json()
print(f"Product: {purchase['product_name']}")
print(f"Quantity: {purchase['quantity']} {purchase['unit_id']}")
print(f"CO2e: {purchase['co2e']} kg")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;

const headers = {
  'x-api-key': apiKey,
  'x-organization-id': orgId
};

const purchaseId = '550e8400-e29b-41d4-a716-446655440000';

axios.get(
  `https://api.dcycle.io/v1/purchases/${purchaseId}`,
  { headers }
)
.then(response => {
  const purchase = response.data;
  console.log(`Product: ${purchase.product_name}`);
  console.log(`Quantity: ${purchase.quantity} ${purchase.unit_id}`);
  console.log(`CO2e: ${purchase.co2e} kg`);
})
.catch(error => console.error(error));

Successful Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "product_name": "Office Supplies",
  "description": "Q1 2024 office supplies order",
  "sector": "Manufacturing",
  "country": "ES",
  "quantity": 1500.00,
  "unit_id": "EUR",
  "purchase_date": "2024-03-15",
  "purchase_type": "spend_based",
  "expense_type": "opex",
  "status": "active",
  "recycled": 0.25,
  "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": 245.5,
  "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", "type": "currency" },
  "uploaded_by": null,
  "uploaded_by_user": null,
  "created_at": "2024-03-15T10:30:00Z",
  "updated_at": "2024-03-15T10:30:00Z"
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{
  "detail": "Invalid API key",
  "code": "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

{
  "detail": "Purchase not found",
  "code": "PURCHASE_NOT_FOUND"
}

Solution: Verify the purchase ID exists and belongs to the organization specified in the header.

422 Validation Error

Cause: Invalid purchase ID format

{
  "detail": [
    {
      "loc": ["path", "purchase_id"],
      "msg": "value is not a valid uuid",
      "type": "type_error.uuid"
    }
  ]
}

Solution: Ensure the purchase ID is a valid UUID format.

Use Cases

Verify Purchase Details Before Update

def get_and_verify_purchase(purchase_id):
    """Get purchase and verify it can be updated"""
    response = requests.get(
        f"https://api.dcycle.io/v1/purchases/{purchase_id}",
        headers=headers
    )

    if response.status_code == 404:
        raise ValueError("Purchase not found")

    purchase = response.json()

    if purchase["status"] == "in_progress":
        raise ValueError("Cannot modify purchase while in progress")

    return purchase

# Verify before updating
purchase = get_and_verify_purchase("550e8400-e29b-41d4-a716-446655440000")
print(f"Current CO2e: {purchase['co2e']} kg")

Check Calculation Status

def check_purchase_calculation(purchase_id):
    """Check if purchase emissions have been calculated"""
    response = requests.get(
        f"https://api.dcycle.io/v1/purchases/{purchase_id}",
        headers=headers
    )
    purchase = response.json()

    if purchase["co2e"] is None:
        return "pending"
    elif purchase["status"] == "error":
        return "error"
    else:
        return "calculated"

status = check_purchase_calculation("550e8400-e29b-41d4-a716-446655440000")
print(f"Calculation status: {status}")

List Purchases

Retrieve all purchases with filtering

Update Purchase

Modify purchase details

Delete Purchase

Remove a purchase

Create Purchase

Add a new purchase

Totals Version History

​Get Purchase

​Request

​Headers

​Path Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​422 Validation Error

​Use Cases

​Verify Purchase Details Before Update

​Check Calculation Status

​Related Endpoints

List Purchases

Update Purchase

Delete Purchase

Create Purchase

Get Purchase

Request

Headers

Path Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

422 Validation Error

Use Cases

Verify Purchase Details Before Update

Check Calculation Status

Related Endpoints