> ## 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.
# Purchase Tools
> MCP tools for managing purchased goods and services (Scope 3) — list, create, and query purchase records
# Purchase Tools
Manage Scope 3 purchased goods and services — each purchase has a product name, quantity, unit, emission methodology (spend-based or supplier-specific), and CO₂e emissions. This is typically the largest Scope 3 category by data volume.
Purchase records can be large. The default page size is **10** — keep `size` ≤ 20 and use pagination to avoid oversized responses. Organizations can have tens of thousands of purchase records.
## `list_purchases`
List purchase records with optional filters.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ----------- | ----------------------------------------------- |
| `organization_id` | string | No | default org | Organization UUID |
| `status` | string | No | — | Status filter: `active`, `error`, `deleted` |
| `purchase_type` | string | No | — | Methodology: `spend_based`, `supplier_specific` |
| `expense_type` | string | No | — | Expense category: `opex`, `capex` |
| `page` | integer | No | 1 | Page number |
| `size` | integer | No | 10 | Results per page (keep ≤ 20) |
The `total` in the response includes records in **all statuses** (active, error, deleted). To match the counts shown by `get_organization_metrics`, filter by `status=active`.
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"items": [
{
"id": "fe4bee9b-...",
"product_name": "chrome steel",
"quantity": 100.0,
"unit": { "name": "metric_tonne_(t)", "type": "solid" },
"purchase_type": "supplier_specific",
"expense_type": "opex",
"status": "active",
"co2e": 185.4,
"purchase_date": "2025-08-01"
}
],
"total": 61764,
"page": 1,
"size": 10,
"pages": 6177
}
```
**Key response fields:**
| Field | Description |
| --------------- | ----------------------------------------------------------------------------------- |
| `product_name` | Name of the purchased product or service |
| `quantity` | Amount in the unit specified by `unit.name` |
| `purchase_type` | `spend_based` (estimated from cost) or `supplier_specific` (supplier-provided data) |
| `expense_type` | `opex` (operational) or `capex` (capital expenditure) |
| `co2e` | Calculated CO₂e emissions in kg |
| `status` | `active`, `error` (calculation failed), or `deleted` |
**Example prompts:**
```
"Show our purchases with supplier-specific emission factors"
"Which purchases are in error status?"
"List our capex purchases"
"What are the top purchases by CO₂ emissions?"
"How many active purchases do we have?"
```
***
## Write Operations
### `create_purchase`
Create a new purchase record for Scope 3 upstream emissions. CO₂e is calculated asynchronously after creation — the response will initially show `co2e` as `null`.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------------------- | ------ | -------- | ------------- | ----------------------------------------------------------------------------------------------- |
| `product_name` | string | **Yes** | — | Name of the product or service (e.g. `"Office Supplies"`, `"Cloud Hosting"`) |
| `quantity` | number | **Yes** | — | Monetary amount spent (must be ≥ 0) |
| `unit_id` | string | **Yes** | — | Currency unit ID (e.g. `"EUR"`, `"USD"`) |
| `purchase_date` | string | **Yes** | — | Date in `YYYY-MM-DD` format |
| `country` | string | **Yes** | — | ISO country code of the supplier (e.g. `"ES"`, `"US"`) |
| `sector` | string | **Yes** | — | Economic sector for emission factor lookup (e.g. `"information_technology"`, `"manufacturing"`) |
| `expense_type` | string | **Yes** | — | `"opex"` (operational) or `"capex"` (capital) |
| `purchase_type` | string | No | `spend_based` | GHG method: `"spend_based"` or `"supplier_specific"` |
| `description` | string | No | — | Optional description |
| `recycled` | number | No | — | Fraction of recycled content (0.0 to 1.0) |
| `supplier_id` | string | No | — | UUID of an existing supplier |
| `custom_emission_factor_id` | string | No | — | UUID of a custom emission factor |
| `organization_id` | string | No | default org | Organization UUID |
CO₂e emissions are calculated in the background after creation. The initial response will show `co2e: null`. Call `list_purchases` after a few seconds to see the calculated value.
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "fe4bee9b-...",
"product_name": "Office Supplies",
"quantity": 1500.0,
"unit_id": "EUR",
"purchase_date": "2025-06-15",
"country": "ES",
"sector": "manufacturing",
"expense_type": "opex",
"purchase_type": "spend_based",
"status": "active",
"co2e": null,
"created_at": "2025-06-15T10:30:00Z"
}
```
**Example prompts:**
```
"Log a purchase of 1500 EUR for office supplies from Spain"
"Create a capex purchase for cloud hosting, 3000 USD, from the US"
"Add a supplier-specific purchase for 500 EUR of recycled packaging"
```
**Common errors:**
| Error | Cause |
| ----------------------- | ------------------------------------------------------------------ |
| 422: Validation error | Missing required fields or invalid values (e.g. negative quantity) |
| 422: "Invalid unit\_id" | The currency/unit ID doesn't exist in the system |
### `update_purchase`
Update an existing purchase record. Only the fields you provide are changed — omitted fields remain unchanged. CO₂e is recalculated after update.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------------------- | ------ | -------- | ----------- | --------------------------------------------------------------- |
| `purchase_id` | string | **Yes** | — | UUID of the purchase to update. Use `list_purchases` to find it |
| `product_name` | string | No | — | New product/service name (max 255 chars) |
| `quantity` | number | No | — | New monetary amount (≥ 0) |
| `unit_id` | string | No | — | New currency unit ID |
| `purchase_date` | string | No | — | New date (`YYYY-MM-DD`) |
| `expense_type` | string | No | — | `"opex"` or `"capex"` |
| `description` | string | No | — | New description (max 500 chars) |
| `recycled` | number | No | — | New recycled content fraction (0.0 to 1.0) |
| `custom_emission_factor_id` | string | No | — | UUID of a custom emission factor override |
| `organization_id` | string | No | default org | Organization UUID |
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "fe4bee9b-...",
"product_name": "Updated Product Name",
"quantity": 2000.0,
"expense_type": "capex",
"status": "active",
"co2e": null,
"updated_at": "2025-07-09T14:00:00Z"
}
```
**Example prompts:**
```
"Change the quantity of purchase abc-123 to 2000 EUR"
"Update purchase xyz to capex"
"Fix the description of purchase abc-123 to 'Annual cloud hosting'"
```
**Common errors:**
| Error | Cause |
| ---------------------------- | ------------------------- |
| 404: "Purchase not found" | Invalid purchase UUID |
| 422: "Invalid expense\_type" | Must be `opex` or `capex` |
***
## Workflows
### Querying purchases
1. **List purchases** — `list_purchases` filtered by type, expense category, or status
2. **Check data quality** — Filter `status=error` to find purchases with calculation issues
3. **View emissions** — `get_greenhouse_gas_emissions` with `category=purchases` for aggregated Scope 3 purchase totals
### Logging a new purchase
1. **Find facility context** — `list_facilities` to understand the organization setup
2. **Create the purchase** — `create_purchase` with product details, amount, and sector
3. **Verify** — `list_purchases` after a few seconds to confirm creation and CO₂e calculation
## Related
REST API endpoint for purchase creation
REST API equivalent with additional filters
Aggregated Scope 3 purchase emissions
Manage purchases from the command line