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:

{
  "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:

{
  "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:

{
  "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

List purchases — list_purchases filtered by type, expense category, or status
Check data quality — Filter status=error to find purchases with calculation issues
View emissions — get_greenhouse_gas_emissions with category=purchases for aggregated Scope 3 purchase totals

Logging a new purchase

Find facility context — list_facilities to understand the organization setup
Create the purchase — create_purchase with product details, amount, and sector
Verify — list_purchases after a few seconds to confirm creation and CO₂e calculation

API: Create Purchase

REST API endpoint for purchase creation

API: List Purchases

REST API equivalent with additional filters

Emissions

Aggregated Scope 3 purchase emissions

CLI

Manage purchases from the command line

Getting Started

Tools Reference

Reference Data

Purchase Tools

Purchase Tools

`list_purchases`

Write Operations

`create_purchase`

`update_purchase`

Workflows

Querying purchases

Logging a new purchase

API: Create Purchase

API: List Purchases

Emissions

CLI

​Purchase Tools

​list_purchases

​Write Operations

​create_purchase

​update_purchase

​Workflows

​Querying purchases

​Logging a new purchase

​Related

API: Create Purchase

API: List Purchases

Emissions

CLI

Purchase Tools

`list_purchases`

Write Operations

`create_purchase`

`update_purchase`

Workflows

Querying purchases

Logging a new purchase

Related