Skip to content
API referencePricing API

List price lists (v2)

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/v2/price-lists

Returns price lists one page at a time. Use page (default 1) and page_size (default 100, maximum 250) to page through the results, order_by to sort them (for example name:asc or updated_at:desc), and source to filter by a comma-separated list of sources. Results are returned in data, with a pagination object giving total, per_page, current_page and total_pages.

Use this endpoint rather than GET /api/v1/price-lists, which returns every price list in one unpaginated array.

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

page?integer

The page of results to fetch

Range1 <= value
Default1
page_size?integer

Number of records per page

Range1 <= value <= 250
Default100
order_by?string

Field to order the search results by

Match^(name|created_at|updated_at):(asc|desc)$
Default"name:asc"
source?array<>

Only return price lists from these sources, as a comma-separated list: custom (set up in the SparkLayer Dashboard), integration (created by an external integration) or platform (reserved for the eCommerce platform). Defaults to all three.

Default

[  "custom",  "integration",  "platform"]

Header Parameters

Site-Id*string

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

Response Body

application/json

application/problem+json

curl -X GET "https://app.sparklayer.io/api/v2/price-lists" \  -H "Authorization: Bearer <ACCESS_TOKEN>" \  -H "Site-Id: jones-climbing"
{  "data": [    {      "slug": "base-list",      "name": "Base Price List",      "currency_code": "GBP",      "source": "custom",      "tax_inclusive_display": false,      "rules": [        {          "source_price_list_slug": "base-list",          "adjustment_percentage": 0.103333,          "adjustment_direction": "plus",          "currency_exchange_rate": 1.254324        }      ]    }  ],  "pagination": {    "total": 0,    "per_page": 0,    "current_page": 0,    "total_pages": 0  }}

PATCHUpdate a price list

Updates only the fields you send (`name`, `currency_code`, `rules` and `tax_inclusive_display`); the slug and source cannot be changed. Sending `rules` replaces all of the existing rules. Changing `currency_code` relabels the prices already on the list with the new currency without converting the amounts. Returns the updated price list, or `404` if it does not exist.

GETList prices in a price list

Returns every price stored on the price list, one entry per SKU and quantity break, ordered by SKU. Prices derived from the list's rules are not included. Send the request with a `Content-Type: text/csv` header to receive the same data as a CSV file. Returns `204` with no body if the price list has no prices, and `404` if the price list does not exist.