Skip to main content

​
Sold Products API

The Sold Products API enables you to manage downstream emissions from products your organization sells. Track products across time periods and geographic markets, with emissions automatically calculated per period for Scope 3 Category 11 (Use of Sold Products) reporting.
New API: These endpoints are part of the new API architecture.

​
Key Features

  • Product Lifecycle Tracking: Manage sold products with time-based periods and country-level sales data
  • Geographic Breakdown: Track quantities sold per country with associated emission factors
  • Period Management: Organize data by reporting periods with overlap detection
  • Emissions Calculation: Automatic calculation of downstream emissions per period
  • Deduplication: Check for existing product-country combinations before uploading

​
Authentication

All endpoints require authentication using either:
  • API Key: Include in x-api-key header
  • JWT Token: Include in Authorization header as Bearer {JWT_TOKEN}

​
Headers

All requests must include:
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef

​
Available Endpoints

​
Product Management

List Sold Products

Retrieve all sold products with optional name filter

Delete Sold Product

Remove a sold product and all related data

Existing Country Sales

Check existing product-country combinations for deduplication

​
Period Management

List Periods

Get all periods for a sold product

Check Period Overlap

Verify if a date range overlaps with existing periods

Delete Period

Remove a period from a sold product

​
Emissions & Sales Data

Period Country Sales

Get country-level sales breakdown for a period

Period Emissions

Get emissions data for a sold product period

​
Data Model

​
Sold Product Object

{
  "product_id": "550e8400-e29b-41d4-a716-446655440000",
  "product_name": "Industrial Compressor X200",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "organization_name": "Acme Manufacturing"
}

​
Period Object

{
  "id": "period-uuid-001",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31"
}

​
Country Sales Object

{
  "items": [
    {
      "id": "sale-uuid-001",
      "quantity": 250.0,
      "unit": {
        "id": "unit-uuid",
        "name": "unit",
        "symbol": "u"
      },
      "location": {
        "country_code": "ES",
        "country_name": "Spain"
      }
    },
    {
      "id": "sale-uuid-002",
      "quantity": 180.0,
      "unit": {
        "id": "unit-uuid",
        "name": "unit",
        "symbol": "u"
      },
      "location": {
        "country_code": "DE",
        "country_name": "Germany"
      }
    }
  ],
  "total_quantity": 430.0,
  "file": null
}

​
Period Emissions Object

{
  "items": [
    {
      "type": "use_phase",
      "status": "calculated",
      "quantity": 12500.0,
      "use_of_product_data_id": "use-data-uuid"
    },
    {
      "type": "end_of_life",
      "status": "calculated",
      "quantity": 350.0,
      "use_of_product_data_id": null
    }
  ]
}

​
Sold Product Attributes

FieldTypeDescription
product_idUUIDUnique product identifier
product_namestringName of the sold product
organization_idUUIDOwning organization
organization_namestringOrganization display name

​
Period Attributes

FieldTypeDescription
idUUIDPeriod identifier
start_datedatePeriod start date (YYYY-MM-DD)
end_datedatePeriod end date (YYYY-MM-DD)

​
Emissions Attributes

FieldTypeDescription
typestringEmission type (e.g., use_phase, end_of_life)
statusstringCalculation status
quantityfloatEmissions quantity (kgCO2e)
use_of_product_data_idUUIDReference to use-of-product data (if applicable)

​
Error Handling

​
Common HTTP Status Codes

StatusMeaningSolution
200Success-
204No Content (delete successful)-
400Bad Request / Cannot delete last periodCheck constraints
401UnauthorizedVerify API key
404Not FoundCheck resource ID or organization
422Validation ErrorReview error details in response
500Server ErrorContact support if persists

​
Common Use Cases

​
List all sold products and their periods

import requests

headers = {
    "x-api-key": "YOUR_API_KEY",
    "x-organization-id": "YOUR_ORG_ID"
}

# Get all sold products
products = requests.get(
    "https://api.dcycle.io/v2/sold-products/",
    headers=headers
).json()

for product in products["items"]:
    print(f"Product: {product['product_name']}")

    # Get periods for each product
    periods = requests.get(
        f"https://api.dcycle.io/v2/sold-products/{product['product_id']}/periods",
        headers=headers
    ).json()

    for period in periods["items"]:
        print(f"  Period: {period['start_date']} to {period['end_date']}")

​
Check for existing data before upload

# Check if data already exists for a product-country-period combination
existing = requests.get(
    "https://api.dcycle.io/v2/sold-products/existing-country-sales",
    headers=headers,
    params={
        "start_date": "2024-01-01",
        "end_date": "2024-12-31"
    }
).json()

for org_data in existing["items"]:
    for item in org_data["items"]:
        print(f"Existing: {item['product_name']} in {item['country_name']}")

​
Get emissions breakdown for a period

emissions = requests.get(
    f"https://api.dcycle.io/v2/sold-products/{product_id}/periods/{period_id}/emissions",
    headers=headers
).json()

for emission in emissions["items"]:
    print(f"{emission['type']}: {emission['quantity']} kgCO2e ({emission['status']})")

ISO 14064 Category 5

ISO 14064 downstream emissions from sold products

Purchases API

Track upstream purchased goods and services

GHG Protocol Scope 3

Complete Scope 3 emissions guide

Emissions API

View aggregated emissions summaries