Skip to content
API referencePurchasing API

List purchases

For AI assistants: the facts every SparkLayer API call needs
  • Base URLs: Live https://app.sparklayer.io, test https://test.app.sparklayer.io. Each environment has its own data and its own API keys.
  • Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
  • Access token: POST {base}/api/auth/token with a Site-Id header and a JSON body (not form-encoded): {"grant_type":"client_credentials","client_id":"…","client_secret":"…"}. It returns access_token, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
  • Every request: Authorization: Bearer <access_token> and Site-Id: <site id>, plus Content-Type: application/json when there is a body. Set a User-Agent that names your integration.
  • Errors: RFC 7807 problem details: title, status, detail and an optional errors[] of { code, message, property }. Some error responses have no body. Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409s with exponential backoff; on 401, get a new token once and retry; don't retry other 4xx without changing the request.
  • Pagination: Most list endpoints return everything. GET /api/v2/price-lists pages with page and page_size (up to 250) until pagination.current_page equals total_pages. GET /api/v1/purchases uses limit (up to 500) and offset: stop when a page has fewer than limit results.
  • Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer GET /api/v2/price-lists over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.
  • Read the docs as Markdown: Add .md to any page URL. Index of every page: docs.sparklayer.io/llms.txt. Every API operation, compactly: docs.sparklayer.io/llms-api.txt. The developer guides in full: docs.sparklayer.io/developers/llms.txt.
  • OpenAPI specs: core, ordering, pricing, purchasing, stock, files, sync-log: https://docs.sparklayer.io/openapi/<api>.yaml (also .json). Ignite: https://docs.sparklayer.io/openapi/ignite.yaml.
  • MCP: Search and read these docs from your assistant with the docs MCP server at https://docs.sparklayer.io/mcp.
Build with AI: ready-made prompts and MCP setup
GET
/api/v1/purchases

Lists purchases, filtered by customer, company, status, type, quote status, search term and date ranges. Results are sorted by order_by, newest first when you don't set it. Page through them with limit (up to 500) and offset, and stop when a page has fewer than limit results.

Authorization

bearerAuth
AuthorizationBearer <token>

Send Authorization: Bearer <access_token>, together with your Site-Id header, on every request. Get the token from POST /api/auth/token with your Site ID in the Site-Id header and a JSON body (not form-encoded, so standard OAuth 2.0 client libraries don't work): {"grant_type": "client_credentials", "client_id": "…", "client_secret": "…"}. Tokens are valid for 3,600 seconds and there is no refresh token: request a new one shortly before it expires. Create API credentials in the SparkLayer Dashboard under Settings > API. See Authentication.

In: header

Query Parameters

limit?integer

Limit the number of results returned

Range1 <= value <= 500
offset?integer

Skip this many results, for paging. Sorted by order_by, newest first when none is given

Range0 <= value
order_by?string

The date field to sort by, in descending order (newest first). Without it, results are newest first.

Value in

  • "created_at"
  • "updated_at"
  • "placed_at"
  • "calculated_submitted_at"
  • "shipping_requested_date"
customer_identifiers[sparklayer]?string

Filter by customer_identifiers[sparklayer]. Accepts comma-separated values. Maximum total length of all values is 2000 characters.

Length1 <= length <= 2000
customer_identifiers[sparklayer_impersonator]?string

Filter by customer_identifiers[sparklayer_impersonator]. Accepts comma-separated values. Maximum total length of all values is 2000 characters.

Length1 <= length <= 2000
customer_identifiers[sparklayer_sales_rep]?string

Filter by customer_identifiers[sparklayer_sales_rep]. Accepts comma-separated values. Maximum total length of all values is 2000 characters.

Length1 <= length <= 2000
customer_identifiers[sparklayer_impersonator_assignee]?string

Filter by customer_identifiers[sparklayer_impersonator_assignee]. Accepts comma-separated values. Maximum total length of all values is 2000 characters. To get purchases that have no assignee, include a string value of 'NULL'.

Length1 <= length <= 2000
company[id]?string

Filter by company[id]. Accepts comma-separated values. Maximum total length of all values is 2000 characters. Use this rather than listing every section id to report on a whole company.

Length1 <= length <= 2000
company[section_id]?string

Filter by company[section_id]. Accepts comma-separated values. Maximum total length of all values is 2000 characters.

Length1 <= length <= 2000
status?string

Only purchases with this status.

Value in

  • "incoming"
  • "processing"
  • "shipped"
  • "part_shipped"
  • "cancelled"
  • "returned"
  • "part_returned"
  • "varied"
type?string

Only purchases of this type.

Value in

  • "order"
  • "quote"
  • "cart"
  • "awaiting_approval"
  • "awaiting_merchant"
  • "archived"
  • "platform_archived"
  • "pending_recurring_order"
quote_status?string

Only quotes with this quote status slug.

search?string

Only purchases that match this search term.

dates[last_updated][lte]?string

Only purchases last updated on or before this date.

Length1 <= length
dates[last_updated][gte]?string

Only purchases last updated on or after this date.

Length1 <= length
dates[placed][lte]?string

Only purchases placed on or before this date.

Length1 <= length
dates[placed][gte]?string

Only purchases placed on or after this date.

Length1 <= length
dates[submitted][lte]?string

Only purchases submitted on or before this date.

Length1 <= length
dates[submitted][gte]?string

Only purchases submitted on or after this date.

Length1 <= length
dates[shipping_requested][lte]?string

Only purchases with a requested shipping date on or before this date.

Length1 <= length
dates[shipping_requested][gte]?string

Only purchases with a requested shipping date on or after this date.

Length1 <= length

Header Parameters

Site-Id*string

Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard.

Length1 <= length

Response Body

application/json

application/problem+json

curl -X GET "https://app.sparklayer.io/api/v1/purchases" \  -H "Authorization: Bearer <ACCESS_TOKEN>" \  -H "Site-Id: jones-climbing"
[  {    "type": "order",    "purchase_identifiers": {      "sparklayer": "63428136-658f-48a6-beb7-7f333dfd9686",      "platform": "123456789",      "internal": "string",      "visible": "B2B01123"    },    "customer_identifiers": {      "sparklayer": "4217ba4f-7618-4e3b-b1af-9055639b18d1",      "sparklayer_impersonator": "4217ba4f-7618-4e3b-b1af-9055639b18d1",      "sparklayer_impersonator_assignee": "4217ba4f-7618-4e3b-b1af-9055639b18d1",      "sparklayer_child": "4217ba4f-7618-4e3b-b1af-9055639b18d1"    },    "company": {      "id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",      "section_id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",      "section_name": "Bristol"    },    "payment_method": "quote",    "dates": {      "created_at": "2020-01-01T00:00:00+02:00",      "updated_at": "2020-01-01T00:00:00+02:00",      "placed_at": "2020-01-01T00:00:00+02:00",      "to_be_placed_at": "2020-01-01T00:00:00+02:00",      "calculated_submitted_at": "2020-01-01T00:00:00+02:00",      "expires_at": "2020-01-01T00:00:00+02:00",      "payment_due_at": "2020-01-01T00:00:00+02:00"    },    "customer_reference": "Please deliver to the back of the store",    "po_number": "PO-001",    "shipping_requested_date": "2020-01-01T00:00:00+02:00",    "recurring_purchase": {      "template_id": "0f8fad5b-d9cb-469f-a165-70867728950e",      "cancelled_at": "2020-01-01T00:00:00+02:00",      "to_be_placed_at_initial": "2020-01-01T00:00:00+02:00"    },    "currency_code": "GBP",    "currency_code_base": "GBP",    "calculated_shipping_address": "John Spark, SparkLayer, SparkLayer HQ, Example City, 12345",    "calculated_total": {      "number": "15.99",      "currency": "GBP"    },    "calculated_total_usd": {      "number": "15.99",      "currency": "GBP"    },    "calculated_total_base": {      "number": "15.99",      "currency": "GBP"    },    "calculated_fulfilment_status": "processing",    "quote": {      "status_slug": "string",      "status": {        "id": "string",        "name": "string",        "slug": "string",        "default": true,        "next": "string",        "actions": [          "edit_quote"        ],        "created_at": "2019-08-24T14:15:22Z",        "updated_at": "2019-08-24T14:15:22Z",        "deleted_at": "2019-08-24T14:15:22Z"      },      "expiry": "2020-01-01T00:00:00+02:00"    },    "payment_status": "unpaid",    "total_paid": {      "number": "15.99",      "currency": "GBP"    }  }]

DELDelete a purchase

Deletes the purchase that matches `lookupBy` and `identifier`, and returns `204`. Returns `404` if no purchase matches.

GETList purchase history

Returns the history of the purchase that matches `lookupBy` and `identifier`: its message, note, email and update events. Returns `404` if no purchase matches.