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

# Purchases API

> Manage purchased goods and services data for Scope 3 Category 1 emissions

# Purchases API

The Purchases API allows you to create, retrieve, update, and delete purchase records for tracking Scope 3 Category 1 (Purchased Goods and Services) emissions. Purchases can be tracked using spend-based or supplier-specific methodologies for accurate CO2e calculations.

<Note>
  **GHG Protocol Scope 3 Category 1**

  Purchased Goods and Services covers emissions from the production of goods and services purchased by your organization. This API helps you collect and manage the data needed for accurate Category 1 reporting using either spend-based or supplier-specific emission factors.
</Note>

## Key Features

* **Purchase Management**: Create and manage purchase records with supplier and product information
* **Spend-Based Tracking**: Calculate emissions based on monetary spend and sector-specific emission factors
* **Supplier-Specific Factors**: Use custom emission factors for more accurate calculations
* **CAPEX/OPEX Classification**: Distinguish between capital and operational expenditures
* **File Attachments**: Link purchases to uploaded documents (invoices, receipts)
* **Pagination Support**: Efficiently retrieve large purchase lists
* **Filtering**: Filter purchases by status, type, expense type, and file

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

<CardGroup cols={2}>
  <Card title="List Purchases" icon="list" href="/api-reference/purchases/list">
    Retrieve all purchases with filtering and pagination
  </Card>

  <Card title="Get Purchase" icon="receipt" href="/api-reference/purchases/get">
    Get a specific purchase by ID
  </Card>

  <Card title="Create Purchase" icon="plus" href="/api-reference/purchases/create">
    Add a new purchase to your organization
  </Card>

  <Card title="Update Purchase" icon="pencil" href="/api-reference/purchases/update">
    Modify purchase details
  </Card>

  <Card title="Delete Purchase" icon="trash" href="/api-reference/purchases/delete">
    Remove a purchase from your organization
  </Card>
</CardGroup>

## Data Model

### Purchase Object

The purchase object contains detailed information about a purchased good or service:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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": "supplier-123",
  "custom_emission_factor_id": null,
  "file_id": "660e8400-e29b-41d4-a716-446655440000",
  "file_name": "invoice_q1_2024.pdf",
  "file_url": "https://storage.dcycle.io/...",
  "co2e": 245.5,
  "frequency": "once",
  "created_at": "2024-03-15T10:30:00Z",
  "updated_at": "2024-03-15T10:30:00Z"
}
```

### Purchase Attributes

| Field                       | Type     | Description                                              |
| --------------------------- | -------- | -------------------------------------------------------- |
| `id`                        | UUID     | Unique identifier for the purchase                       |
| `organization_id`           | UUID     | Organization the purchase belongs to                     |
| `product_name`              | string   | Name of the product or service (max 255 chars)           |
| `description`               | string   | Optional description (max 500 chars)                     |
| `sector`                    | string   | Economic sector for emission factor lookup               |
| `country`                   | string   | 2-letter ISO country code                                |
| `quantity`                  | float    | Purchase amount (monetary or physical units)             |
| `unit_id`                   | string   | Unit of measurement (e.g., EUR, USD, kg)                 |
| `purchase_date`             | date     | Date of purchase (YYYY-MM-DD)                            |
| `purchase_type`             | string   | Calculation method: `spend_based` or `supplier_specific` |
| `expense_type`              | string   | Classification: `capex` or `opex`                        |
| `status`                    | string   | Purchase status (see Status Types)                       |
| `recycled`                  | float    | Recycled content percentage (0-1)                        |
| `supplier_id`               | string   | Optional supplier identifier                             |
| `custom_emission_factor_id` | UUID     | Custom emission factor for supplier-specific             |
| `file_id`                   | UUID     | Linked file/document ID                                  |
| `file_name`                 | string   | Name of linked file                                      |
| `file_url`                  | string   | URL to download linked file                              |
| `co2e`                      | float    | Calculated CO2 equivalent emissions (kg)                 |
| `frequency`                 | string   | Purchase frequency: `once`                               |
| `created_at`                | datetime | When the purchase was created                            |
| `updated_at`                | datetime | When the purchase was last updated                       |

## Purchase Types

| Type                | Description                                 | Emission Factor Source                                        |
| ------------------- | ------------------------------------------- | ------------------------------------------------------------- |
| `spend_based`       | Calculate emissions based on monetary spend | Sector-specific factors from emission databases               |
| `supplier_specific` | Use supplier-provided emission factors      | Custom emission factor linked via `custom_emission_factor_id` |

<Note>
  **Spend-Based vs Supplier-Specific**

  * **Spend-based** is easier to implement but less accurate. It uses average emission factors for economic sectors.
  * **Supplier-specific** requires more data but provides more accurate results by using actual emission factors from your suppliers.
</Note>

## Expense Types

| Type    | Description             | GHG Protocol Category                           |
| ------- | ----------------------- | ----------------------------------------------- |
| `capex` | Capital Expenditure     | Scope 3 Category 2 (Capital Goods)              |
| `opex`  | Operational Expenditure | Scope 3 Category 1 (Purchased Goods & Services) |

## Status Types

| Status        | Description                                       |
| ------------- | ------------------------------------------------- |
| `active`      | Purchase is active and included in calculations   |
| `pending`     | Purchase is pending review                        |
| `in_progress` | Purchase is being processed                       |
| `in_review`   | Purchase is under review                          |
| `inactive`    | Purchase is inactive (excluded from calculations) |
| `error`       | Error occurred during processing                  |

## CO2e Calculation

Emissions are calculated using different methodologies based on purchase type:

### Spend-Based Method

```
CO2e = Spend Amount (EUR) x Sector Emission Factor (kg CO2e/EUR) x (1 - Recycled %)
```

### Supplier-Specific Method

```
CO2e = Quantity x Custom Emission Factor (from supplier)
```

## Workflow

### Tracking Purchases

1. **Create Purchase**: Add purchase with product, quantity, and sector information
2. **Set Type**: Choose spend-based or supplier-specific calculation method
3. **Link Supplier Factor** (optional): For supplier-specific, link a custom emission factor
4. **Query Results**: Retrieve purchases to see calculated CO2e

### Bulk Upload

For large volumes of purchases, use the CSV bulk upload feature in the Dcycle app or the Legacy API bulk upload endpoint.

## Error Handling

### Common HTTP Status Codes

| Status | Meaning                        | Solution                            |
| ------ | ------------------------------ | ----------------------------------- |
| 200    | Success                        | -                                   |
| 201    | Created                        | -                                   |
| 204    | No Content (delete successful) | -                                   |
| 400    | Bad Request                    | Check request parameters and format |
| 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         |

### Error Response Format

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Error description",
  "code": "ERROR_CODE"
}
```

## Use Cases

### Track Office Supplies Spend

Monitor CO2e emissions for office supply purchases:

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

# Create purchase
purchase = requests.post(
    "https://api.dcycle.io/v1/purchases",
    headers=headers,
    json={
        "product_name": "Office Supplies Q1",
        "sector": "Manufacturing",
        "country": "ES",
        "quantity": 2500.00,
        "unit_id": "EUR",
        "purchase_date": "2024-03-15",
        "purchase_type": "spend_based",
        "expense_type": "opex",
        "recycled": 0.3
    }
).json()

print(f"CO2e: {purchase['co2e']} kg")
```

### Calculate Category 1 Totals

Sum up all purchased goods and services emissions:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Get all active purchases
response = requests.get(
    "https://api.dcycle.io/v1/purchases",
    headers=headers,
    params={"status[]": ["active"], "size": 100}
).json()

total_co2e = sum(p.get("co2e", 0) for p in response["items"])
print(f"Scope 3 Category 1 Total: {total_co2e} kg CO2e ({total_co2e/1000:.1f} tonnes)")
```

## Related Documentation

<CardGroup cols={2}>
  <Card title="Scope 3 Category 1 Guide" icon="shopping-cart" href="/guides/emissions/scope-3-category-1-purchased-goods">
    Complete tutorial for tracking Scope 3 Category 1 emissions
  </Card>

  <Card title="Custom Emission Factors" icon="chart-line" href="/api-reference/legacy/custom-emission-factors/overview">
    Create supplier-specific emission factors
  </Card>

  <Card title="Authentication Guide" icon="key" href="/docs/authentication">
    Learn how to authenticate API requests
  </Card>

  <Card title="Suppliers API" icon="building" href="/api-reference/legacy/suppliers/list">
    Manage supplier data
  </Card>

  <Card title="MCP Tools" icon="robot" href="/mcp/purchases">
    Query purchase data from AI assistants via MCP
  </Card>
</CardGroup>