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

x-api-key

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

x-organization-id

string

required

Your organization UUIDExample: 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"

country

string

required

2-letter ISO country code where the purchase was madeExample: "ES"

quantity

number

required

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

unit_id

string

required

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

purchase_date

string

required

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

expense_type

string

required

Expense classificationAvailable values: capex, opexExample: "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 emissionsAvailable values: spend_based, supplier_specificExample: "spend_based"

status

string

default:"active"

Initial status of the purchaseAvailable values: active, pending, in_progress, in_review, inactiveExample: "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 referenceExample: "supplier-123"

custom_emission_factor_id

string

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

frequency

string

default:"once"

Purchase frequencyAvailable values: onceExample: "once"

file_id

string

UUID of linked file/documentExample: "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 fileExample: "https://storage.dcycle.io/..."

Response

Returns the created purchase object with calculated emissions.

string

Unique identifier (UUID) of the created purchase

co2e

number | null

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

See Get Purchase for the complete response schema.

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",
    "country": "ES",
    "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"
  }'

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",
  "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": null,
  "custom_emission_factor_id": null,
  "file_id": null,
  "file_name": null,
  "file_url": null,
  "co2e": 245.5,
  "frequency": "once",
  "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, country, 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
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

Create Spend-Based Purchase

Track a purchase using monetary spend and sector emission factors:

def create_spend_based_purchase(product_name, sector, country, 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,
            "country": country,
            "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",
    country="US",
    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",
            "country": "ES",
            "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, country, 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,
            "country": country,
            "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",
    country="DE",
    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",
        "country": "ES",
        "quantity": 10000.00,
        "unit_id": "EUR",
        "purchase_date": "2024-03-01",
        "expense_type": "opex"
    },
    {
        "product_name": "IT Services",
        "sector": "Information and communication",
        "country": "ES",
        "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

Introduction

Logistics

Vehicles

Unknown Vehicles

Vehicle Fuels

Business Travels

Employees

Commuting Periods

Invoices

Purchases

Create Purchase

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

List Purchases

Get Purchase

Update Purchase

Custom Emission Factors

Introduction

Logistics

Vehicles

Unknown Vehicles

Vehicle Fuels

Business Travels

Employees

Commuting Periods

Invoices

Purchases

​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