Skip to main content
GET
List Purchases

List Purchases

Retrieve a paginated list of purchases in your organization with support for filtering by status, type, expense type, date range, supplier, CO2e calculation status, and more.

Request

Headers

string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

array[string]
Filter by purchase statusAvailable values: active, pending, in_progress, in_review, inactive, errorExample: status[]=active&status[]=pending
array[string]
Filter by purchase calculation typeAvailable values: spend_based, supplier_specificExample: purchase_type[]=spend_based
array[string]
Filter by expense classificationAvailable values: capex, opexExample: expense_type[]=opex
array[string]
Filter by linked file ID (UUID)Example: file_id[]=550e8400-e29b-41d4-a716-446655440000
Search by description or supplier name (case-insensitive substring match)Example: office supplies
string
Filter by purchase description (substring match)
array[string]
Filter by supplier UUIDExample: supplier_id[]=550e8400-e29b-41d4-a716-446655440000
array[string]
Filter by currency/unit UUIDExample: unit_id[]=eur-unit-uuid
date
Filter purchases with purchase_date on or after this date (inclusive)Example: 2024-01-01
date
Filter purchases with purchase_date on or before this date (inclusive)Example: 2024-12-31
date
Filter purchases created on or after this date (inclusive)Example: 2024-01-01
date
Filter purchases created on or before this date (inclusive)Example: 2024-12-31
string
Filter by CO2e calculation statusAvailable values: calculated, not_calculated
string
Sort field. Prefix with - for descending order.Available values: purchase_date, created_at, description, quantity, expense_type, status, product_name, sector, country, recycled, file_name, co2eExamples: co2e, -quantity, -purchase_date
string
Advanced per-column filter expression. Each clause is field:operatorValue, and multiple clauses are separated by $.Operators: gt (greater than), lt (less than), gte (≥), lte (≤), bt[min,max] (between), eq (equals), neq (not equals), contains (substring match)Example: quantity:gt100$co2e:bt[10,500] — quantity > 100 AND CO2e between 10 and 500
string
How to combine filter_by clauses across different fields. Default combines with AND.Available values: any (OR — matches if any clause is true), all (AND — all clauses must match)Example: any
string
Comma-separated list of field names whose same-field filter_by clauses should combine with OR instead of AND.Example: status,expense_type — multiple status or expense_type filters use OR logic
integer
default:"1"
Page number for paginationExample: 2
integer
default:"50"
Number of items per page (max 100)Example: 50

Response

array[object]
Array of purchase objects
integer
Total number of purchases matching the filter
integer
Current page number
integer
Number of items per page
string
16-character hex hash of the applied filters. Pass this to the bulk delete by filters endpoint to ensure consistency.

Example

Successful Response

Common Errors

401 Unauthorized

Cause: Missing or invalid API key
Solution: Verify your API key is valid and active. Get a new one from Settings -> API.

404 Not Found

Cause: Organization not found
Solution: Verify that the x-organization-id header contains a valid organization UUID.

422 Validation Error

Cause: Invalid query parameters
Solution: Check that page size is between 1 and 100, and that filter values are valid enums.

Use Cases

Get All Active Purchases

Retrieve only active purchases:

Filter by Expense Type

Get only operational expenditures:

Calculate Category 1 Totals

Sum up all purchased goods and services emissions:

Group by Sector

Analyze purchases by economic sector:

Pagination Guide

Navigate through large purchase lists efficiently:

Get Purchase

Get a specific purchase by ID

Create Purchase

Add a new purchase to your organization

Update Purchase

Modify purchase details

Delete Purchase

Remove a purchase