Create Purchase

Add a new purchase to your organization for Scope 3 Category 1 tracking

POST /v1/purchases

Create Purchase

JavaScript

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>',
    non_currency_quantity: 123,
    non_currency_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));

200

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

← Purchases API

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

x-api-key · string · required

Your API key for authentication

Example: sk_live_1234567890abcdef

x-organization-id · string · required

Your organization UUID

Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Content-Type · string · required

Must be application/json

Body Parameters

product_name · string · required

Name of the product or service purchased (max 255 characters)

Example: "Office Supplies"

sector · 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).

quantity · number · required

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

Example: 1500.00

A purchase needs one amount pair, not both: monetary (quantity + unit_id) or physical (non_currency_quantity + non_currency_unit_id). Sending half a pair, or neither, is rejected. Spend-based factors price the monetary pair.

unit_id · uuid

Currency the monetary quantity is expressed in. This is a unit id — a UUID from the units catalog, not a currency code such as EUR.

Retrieve it from GET /v2/units, which works with your API key. Currencies have no type filter, so request the full catalog and match on the ISO code in the name — searching for (eur) finds the euro

Example: "d3e37f2b-0fc3-4532-82f8-3890ab56ad37" (euros)

non_currency_quantity · number

Physical amount of the purchase, when you track quantity instead of spend. Must travel together with non_currency_unit_id.

Example: 500

non_currency_unit_id · uuid

Unit of non_currency_quantity — a unit id from the catalog, not a symbol such as kg.

Retrieve available options from GET /v2/units?type=non_currency_purchases, which works with your API key.

Example: "61743a63-ff70-459c-9567-5eee8f7dfd5c" (kilogram)

purchase_date · string · required

Date of purchase in YYYY-MM-DD format

Example: "2024-03-15"

expense_type · string · required

Expense classification

Available values: capex, opex

Example: "opex"

description · string

Optional description of the purchase (max 500 characters)

Example: "Q1 2024 office supplies order"

purchase_type · string · default: "spend_based"

Calculation method for emissions. Kept only for purchases priced with a custom_emission_factor_id; for any other purchase it is replaced by the method its emission factor implies

Available values: spend_based, supplier_specific, average_data

Example: "spend_based"

status · string · default: "active"

Initial status of the purchase

Available values: active, pending, in_progress, in_review, inactive

Example: "active"

recycled · number

Recycled content percentage (0 to 1). Reduces calculated emissions.

Example: 0.25 (25% recycled content)

supplier_id · string

Optional supplier identifier for reference

Example: "supplier-123"

custom_emission_factor_id · string

UUID of custom emission factor for supplier-specific calculations

Despite the name, this field holds the id of a custom emission group, not of an individual factor. Retrieve available options from GET /custom_emission_groups/light

Example: "770e8400-e29b-41d4-a716-446655440000"

frequency · string · default: "once"

Purchase frequency

Available values: once

Example: "once"

file_id · string

UUID of linked file/document

Example: "660e8400-e29b-41d4-a716-446655440000"

file_name · string

Name of linked file (max 255 characters)

Example: "invoice_q1_2024.pdf"

file_url · string

URL of linked file

Example: "https://storage.dcycle.io/..."

Response

Returns the created purchase object with HTTP status 201 Created.

id · string

Unique identifier (UUID)

organization_id · string

Organization UUID

product_name · string | null

Name of the product or service

description · string | null

Optional description

sector · string | null

Economic sector

quantity · number | null

Purchase amount

unit_id · uuid | null

Currency unit id of the monetary quantity

purchase_date · date | null

Date of purchase

purchase_type · string | null

Calculation method, set from the emission factor that prices the purchase: spend_based, supplier_specific or average_data

expense_type · string

Classification: capex or opex

status · string | null

Purchase status

recycled · number | null

Recycled content percentage (0-1)

supplier_id · string | null

Supplier identifier

custom_emission_factor_id · string | null

Custom emission factor UUID

file_id · string | null

Linked file UUID

file_name · string | null

Linked file name

file_url · string | null

Linked file download URL

co2e · number | null

Calculated CO2 equivalent emissions in kg (may be null while calculation is pending)

frequency · string | null

Purchase frequency

exchange_rate_to_eur · number | null

Exchange rate used to convert the purchase amount to EUR

exchange_rate_date · date | null

Date used for the exchange rate lookup

custom_emission_group · 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

last_purchase_timestamp · datetime | null

Timestamp of the most recent purchase in a recurring series

supplier · 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

unit · object | null

Unit of measurement details

Show Unit Object

id · string

Unit UUID

name · string

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

type · string

Unit category (e.g. currency, weight)

uploaded_by · string | null

UUID of the user who created this record

uploaded_by_user · 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

created_at · datetime

Timestamp when the purchase was created

updated_at · datetime | null

Timestamp when the purchase was last updated

Example

cURL

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": "d3e37f2b-0fc3-4532-82f8-3890ab56ad37",
    "purchase_date": "2024-03-15",
    "expense_type": "opex",
    "purchase_type": "spend_based",
    "recycled": 0.25,
    "description": "Q1 2024 office supplies order"
  }'

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": "d3e37f2b-0fc3-4532-82f8-3890ab56ad37",
  "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": "d3e37f2b-0fc3-4532-82f8-3890ab56ad37", "name": "euros_(eur)", "type": "fiat_currency" },
  "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 one of spend_based, supplier_specific or average_data

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_unit_id, 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_unit_id,
            "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_unit_id="d3e37f2b-0fc3-4532-82f8-3890ab56ad37",  # euros_(eur)
    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_id, 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",
            "non_currency_quantity": quantity,
            "non_currency_unit_id": unit_id,
            "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_id="61743a63-ff70-459c-9567-5eee8f7dfd5c",  # kilogram_(kg)
    date="2024-03-10",
    custom_factor_id="770e8400-e29b-41d4-a716-446655440000",
    supplier_id="c4a91f38-7b62-4d15-9e08-2f5a6d3b81ce"
)

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_unit_id,
            "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_unit_id="d3e37f2b-0fc3-4532-82f8-3890ab56ad37",  # euros_(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": "d3e37f2b-0fc3-4532-82f8-3890ab56ad37",
        "purchase_date": "2024-03-01",
        "expense_type": "opex"
    },
    {
        "product_name": "IT Services",
        "sector": "Information and communication",
        "quantity": 5000.00,
        "unit_id": "d3e37f2b-0fc3-4532-82f8-3890ab56ad37",
        "purchase_date": "2024-03-01",
        "expense_type": "opex"
    }
])
print(f"Created {len(purchases)} purchases")

Related Endpoints

List Purchases

Retrieve all purchases

Get Purchase

Get purchase details

Update Purchase

Modify purchase details

Custom Emission Factors

Create supplier-specific factors