List Purchases
List Purchases
Retrieve all purchases with filtering and pagination support
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_1234567890abcdefstring
required
Your organization UUIDExample:
a8315ef3-dd50-43f8-b7ce-d839e68d51faQuery Parameters
array[string]
Filter by purchase statusAvailable values:
active, pending, in_progress, in_review, inactive, errorExample: status[]=active&status[]=pendingarray[string]
Filter by purchase calculation typeAvailable values:
spend_based, supplier_specificExample: purchase_type[]=spend_basedarray[string]
Filter by expense classificationAvailable values:
capex, opexExample: expense_type[]=opexarray[string]
Filter by linked file ID (UUID)Example:
file_id[]=550e8400-e29b-41d4-a716-446655440000string
Search by description or supplier name (case-insensitive substring match)Example:
office suppliesstring
Filter by purchase description (substring match)
array[string]
Filter by supplier UUIDExample:
supplier_id[]=550e8400-e29b-41d4-a716-446655440000array[string]
Filter by currency/unit UUIDExample:
unit_id[]=eur-unit-uuiddate
Filter purchases with
purchase_date on or after this date (inclusive)Example: 2024-01-01date
Filter purchases with
purchase_date on or before this date (inclusive)Example: 2024-12-31date
Filter purchases created on or after this date (inclusive)Example:
2024-01-01date
Filter purchases created on or before this date (inclusive)Example:
2024-12-31string
Filter by CO2e calculation statusAvailable values:
calculated, not_calculatedstring
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_datestring
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 500string
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: anystring
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 logicinteger
default:"1"
Page number for paginationExample:
2integer
default:"50"
Number of items per page (max 100)Example:
50Response
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 key404 Not Found
Cause: Organization not foundx-organization-id header contains a valid organization UUID.
422 Validation Error
Cause: Invalid query parametersUse 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:Related Endpoints
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