> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sold Products API

> Track downstream emissions from sold products across markets, periods, and country-level sales

# 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.

<Note>
  **New API**: These endpoints are part of the new API architecture.
</Note>

## 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 an API key included in the `x-api-key` header.

## Headers

All requests must include:

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

## Available Endpoints

### Product Management

<CardGroup cols={2}>
  <Card title="List Sold Products" icon="list" href="/api-reference/sold-products/list">
    Retrieve all sold products with optional name filter
  </Card>

  <Card title="Delete Sold Product" icon="trash" href="/api-reference/sold-products/delete">
    Remove a sold product and all related data
  </Card>

  <Card title="Existing Country Sales" icon="globe" href="/api-reference/sold-products/existing-country-sales">
    Check existing product-country combinations for deduplication
  </Card>
</CardGroup>

### Period Management

<CardGroup cols={2}>
  <Card title="List Periods" icon="calendar" href="/api-reference/sold-products/list-periods">
    Get all periods for a sold product
  </Card>

  <Card title="Check Period Overlap" icon="circle-exclamation" href="/api-reference/sold-products/check-overlap">
    Verify if a date range overlaps with existing periods
  </Card>

  <Card title="Delete Period" icon="calendar-xmark" href="/api-reference/sold-products/delete-period">
    Remove a period from a sold product
  </Card>
</CardGroup>

### Emissions & Sales Data

<CardGroup cols={2}>
  <Card title="Period Country Sales" icon="earth-americas" href="/api-reference/sold-products/country-sales">
    Get country-level sales breakdown for a period
  </Card>

  <Card title="Period Emissions" icon="smog" href="/api-reference/sold-products/emissions">
    Get emissions data for a sold product period
  </Card>
</CardGroup>

## Data Model

### Sold Product Object

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "period-uuid-001",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31"
}
```

### Country Sales Object

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

| Field               | Type   | Description               |
| ------------------- | ------ | ------------------------- |
| `product_id`        | UUID   | Unique product identifier |
| `product_name`      | string | Name of the sold product  |
| `organization_id`   | UUID   | Owning organization       |
| `organization_name` | string | Organization display name |

### Period Attributes

| Field        | Type | Description                    |
| ------------ | ---- | ------------------------------ |
| `id`         | UUID | Period identifier              |
| `start_date` | date | Period start date (YYYY-MM-DD) |
| `end_date`   | date | Period end date (YYYY-MM-DD)   |

### Emissions Attributes

| Field                    | Type   | Description                                      |
| ------------------------ | ------ | ------------------------------------------------ |
| `type`                   | string | Emission type (e.g., `use_phase`, `end_of_life`) |
| `status`                 | string | Calculation status                               |
| `quantity`               | float  | Emissions quantity (kgCO2e)                      |
| `use_of_product_data_id` | UUID   | Reference to use-of-product data (if applicable) |

## Error Handling

### Common HTTP Status Codes

| Status | Meaning                                 | Solution                          |
| ------ | --------------------------------------- | --------------------------------- |
| 200    | Success                                 | -                                 |
| 204    | No Content (delete successful)          | -                                 |
| 400    | Bad Request / Cannot delete last period | Check constraints                 |
| 401    | Unauthorized                            | Verify API key                    |
| 404    | Not Found                               | Check resource ID or organization |
| 422    | Validation Error                        | Review error details in response  |
| 500    | Server Error                            | Contact support if persists       |

## Common Use Cases

### List all sold products and their periods

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests
import os

headers = {
    "x-api-key": os.environ["DCYCLE_API_KEY"],
    "x-organization-id": os.environ["DCYCLE_ORG_ID"],
}

# Get all sold products
products = requests.get(
    "https://api.dcycle.io/v1/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/v1/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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Check if data already exists for a product-country-period combination
existing = requests.get(
    "https://api.dcycle.io/v1/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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
emissions = requests.get(
    f"https://api.dcycle.io/v1/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']})")
```

## Related Documentation

<CardGroup cols={2}>
  <Card title="ISO 14064 Category 5" icon="certificate" href="/guides/emissions/iso-14064-category-5-products-sold">
    ISO 14064 downstream emissions from sold products
  </Card>

  <Card title="Purchases API" icon="cart-shopping" href="/api-reference/purchases/overview">
    Track upstream purchased goods and services
  </Card>

  <Card title="GHG Protocol Scope 3" icon="leaf" href="/guides/emissions/ghg-protocol-step-4-scope-3">
    Complete Scope 3 emissions guide
  </Card>

  <Card title="Emissions API" icon="chart-line" href="/api-reference/emissions/overview">
    View aggregated emissions summaries
  </Card>
</CardGroup>