Skip to content
API reference

Stock API

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

The Stock API holds the stock level of each SKU at each of your stock locations, such as warehouses. SparkLayer uses these levels to show stock on the storefront.

How it works

  • Stock locations identify where stock is held. Each has a SparkLayer id and your own external_id, and you can use either to refer to it.
  • Stock levels are set in bulk: Update stock levels for multiple SKUs creates or overwrites the level for each SKU and location pair you send, and leaves other pairs unchanged.
  • Get stock levels for multiple SKUs only returns the location with the external ID default unless you ask for all locations or specific ones.

Endpoints

Next steps

Was this page helpful?

Last updated

GETGet a customer's SKU order stats

Returns how many units of each SKU a customer ordered between `start_date` and `end_date`, grouped by `week`, `month` or `quarter`. Give both dates as RFC 3339 date-times with a time zone offset, or `Z` for UTC. Each period is identified by its start date, returned in UTC.

POSTGet stock levels for multiple SKUs

Returns stock levels for the SKUs in `skus`, grouped by SKU. By default only the stock location with the external ID `default` is included: set `filter.all_stock_locations` to `true` to include every location, or pass `filter.stock_location_ids` to choose specific ones. SKUs with no matching stock levels are left out of the response.