Create Purchase

const options = {
  method: 'POST',
  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', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/purchases"

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.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/purchases \
  --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": {}
}

POST

purchases

Create Purchase

const options = {
  method: 'POST',
  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', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/purchases"

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.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/purchases \
  --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": {}
}

Create Purchase

Create a new purchase record to track Scope 3 Category 1 (Purchased Goods and Services) emissions. The purchase can use either spend-based or supplier-specific calculation methods.

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

Body Parameters

string

required

Name of the product or service purchased (max 255 characters)Example: "Office Supplies"

string

required

Economic sector for emission factor lookup (max 255 characters)Example: "Manufacturing"

The purchase no longer accepts a purchase-level country. The country used for the spend-based emission calculation is taken from the purchase’s supplier (supplier_country when creating the supplier, stored on purchase_suppliers.country).

number

required

Purchase amount (must be >= 0). For spend-based, this is the monetary value.Example: 1500.00

string

required

Unit of measurement (e.g., EUR, USD, kg)Example: "EUR"

string

required

Date of purchase in YYYY-MM-DD formatExample: "2024-03-15"

string

required

Expense classificationAvailable values: capex, opexExample: "opex"

string

Optional description of the purchase (max 500 characters)Example: "Q1 2024 office supplies order"

string

default:"spend_based"

Calculation method for emissionsAvailable values: spend_based, supplier_specificExample: "spend_based"

string

default:"active"

Initial status of the purchaseAvailable values: active, pending, in_progress, in_review, inactiveExample: "active"

number

Recycled content percentage (0 to 1). Reduces calculated emissions.Example: 0.25 (25% recycled content)

string

Optional supplier identifier for referenceExample: "supplier-123"

string

UUID of custom emission factor for supplier-specific calculationsExample: "770e8400-e29b-41d4-a716-446655440000"

string

default:"once"

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.pdf"

string

URL of linked fileExample: "https://storage.dcycle.io/..."

Response

Returns the created purchase object with HTTP status 201 Created.

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_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 in kg (may be null while calculation is pending)

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

Show Unit Object

string

Unit UUID

string

Unit name (e.g. euro_(€), kilogram_(kg))

string

Unit category (e.g. currency, weight)

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 POST "https://api.dcycle.io/v1/purchases" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Office Supplies",
    "sector": "Manufacturing",
    "quantity": 1500.00,
    "unit_id": "EUR",
    "purchase_date": "2024-03-15",
    "expense_type": "opex",
    "purchase_type": "spend_based",
    "recycled": 0.25,
    "description": "Q1 2024 office supplies order"
  }'

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,
    "Content-Type": "application/json"
}

data = {
    "product_name": "Office Supplies",
    "sector": "Manufacturing",
    "quantity": 1500.00,
    "unit_id": "EUR",
    "purchase_date": "2024-03-15",
    "expense_type": "opex",
    "purchase_type": "spend_based",
    "recycled": 0.25,
    "description": "Q1 2024 office supplies order"
}

response = requests.post(
    "https://api.dcycle.io/v1/purchases",
    headers=headers,
    json=data
)

purchase = response.json()
print(f"Created purchase: {purchase['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,
  'Content-Type': 'application/json'
};

const data = {
  product_name: 'Office Supplies',
  sector: 'Manufacturing',
  quantity: 1500.00,
  unit_id: 'EUR',
  purchase_date: '2024-03-15',
  expense_type: 'opex',
  purchase_type: 'spend_based',
  recycled: 0.25,
  description: 'Q1 2024 office supplies order'
};

axios.post(
  'https://api.dcycle.io/v1/purchases',
  data,
  { headers }
)
.then(response => {
  const purchase = response.data;
  console.log(`Created purchase: ${purchase.id}`);
  console.log(`CO2e: ${purchase.co2e} kg`);
})
.catch(error => console.error(error.response.data));

Successful Response

Status Code: 201 Created

{
  "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",
  "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": null,
  "custom_emission_factor_id": null,
  "file_id": null,
  "file_name": null,
  "file_url": null,
  "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": null,
  "unit": { "id": "unit-uuid", "name": "EUR" },
  "uploaded_by": null,
  "uploaded_by_user": null,
  "created_at": "2024-03-15T10:30:00Z",
  "updated_at": "2024-03-15T10:30:00Z"
}

Common Errors

400 Bad Request

Cause: Missing required fields or invalid data format

{
  "detail": "field required",
  "code": "MISSING_REQUIRED_FIELD"
}

Solution: Ensure all required fields are provided: product_name, sector, quantity, unit_id, purchase_date, expense_type.

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.

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

Solution: Check that:

recycled is between 0 and 1
quantity is >= 0
expense_type is either capex or opex
purchase_type is either spend_based or supplier_specific

Use Cases

Create Spend-Based Purchase

Track a purchase using monetary spend and sector emission factors:

def create_spend_based_purchase(product_name, sector, amount, currency, date):
    """Create a spend-based purchase"""
    response = requests.post(
        "https://api.dcycle.io/v1/purchases",
        headers=headers,
        json={
            "product_name": product_name,
            "sector": sector,
            "quantity": amount,
            "unit_id": currency,
            "purchase_date": date,
            "expense_type": "opex",
            "purchase_type": "spend_based"
        }
    )
    return response.json()

# Create purchase
purchase = create_spend_based_purchase(
    product_name="Cloud Hosting",
    sector="Information and communication",
    amount=5000.00,
    currency="USD",
    date="2024-03-01"
)
print(f"CO2e: {purchase['co2e']} kg")

Create Supplier-Specific Purchase

Track a purchase using a custom emission factor from your supplier:

def create_supplier_specific_purchase(
    product_name, quantity, unit, date,
    custom_factor_id, supplier_id=None
):
    """Create a supplier-specific purchase"""
    response = requests.post(
        "https://api.dcycle.io/v1/purchases",
        headers=headers,
        json={
            "product_name": product_name,
            "sector": "Custom",
            "quantity": quantity,
            "unit_id": unit,
            "purchase_date": date,
            "expense_type": "opex",
            "purchase_type": "supplier_specific",
            "custom_emission_factor_id": custom_factor_id,
            "supplier_id": supplier_id
        }
    )
    return response.json()

# Create with supplier-specific factor
purchase = create_supplier_specific_purchase(
    product_name="Recycled Paper",
    quantity=500,
    unit="kg",
    date="2024-03-10",
    custom_factor_id="770e8400-e29b-41d4-a716-446655440000",
    supplier_id="paper-supplier-001"
)

Track Capital Goods (CAPEX)

Create a capital expenditure purchase (Scope 3 Category 2):

def create_capex_purchase(product_name, sector, amount, currency, date):
    """Create a capital goods purchase"""
    response = requests.post(
        "https://api.dcycle.io/v1/purchases",
        headers=headers,
        json={
            "product_name": product_name,
            "sector": sector,
            "quantity": amount,
            "unit_id": currency,
            "purchase_date": date,
            "expense_type": "capex",  # Capital expenditure
            "purchase_type": "spend_based",
            "description": "Capital investment"
        }
    )
    return response.json()

# Track equipment purchase
equipment = create_capex_purchase(
    product_name="Manufacturing Equipment",
    sector="Machinery and equipment",
    amount=150000.00,
    currency="EUR",
    date="2024-02-01"
)

Bulk Create Purchases

Create multiple purchases efficiently:

def bulk_create_purchases(purchases_data):
    """Create multiple purchases"""
    created = []
    for purchase_data in purchases_data:
        response = requests.post(
            "https://api.dcycle.io/v1/purchases",
            headers=headers,
            json=purchase_data
        )
        if response.status_code == 201:
            created.append(response.json())
        else:
            print(f"Failed to create: {purchase_data['product_name']}")
    return created

# Create multiple purchases
purchases = bulk_create_purchases([
    {
        "product_name": "Office Rent",
        "sector": "Real estate activities",
        "quantity": 10000.00,
        "unit_id": "EUR",
        "purchase_date": "2024-03-01",
        "expense_type": "opex"
    },
    {
        "product_name": "IT Services",
        "sector": "Information and communication",
        "quantity": 5000.00,
        "unit_id": "EUR",
        "purchase_date": "2024-03-01",
        "expense_type": "opex"
    }
])
print(f"Created {len(purchases)} purchases")

List Purchases

Retrieve all purchases

Get Purchase

Get purchase details

Update Purchase

Modify purchase details

Custom Emission Factors

Create supplier-specific factors

​Create Purchase

​Request

​Headers

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​400 Bad Request

​401 Unauthorized

​422 Validation Error

​Use Cases

​Create Spend-Based Purchase

​Create Supplier-Specific Purchase

​Track Capital Goods (CAPEX)

​Bulk Create Purchases

​Related Endpoints

List Purchases

Get Purchase

Update Purchase

Custom Emission Factors

Create Purchase

Request

Headers

Body Parameters

Response

Example

Successful Response

Common Errors

400 Bad Request

401 Unauthorized

422 Validation Error

Use Cases

Create Spend-Based Purchase

Create Supplier-Specific Purchase

Track Capital Goods (CAPEX)

Bulk Create Purchases

Related Endpoints