Skip to content
API reference

Core 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 Core API manages the configuration that controls how your B2B customers buy: customer groups, discounts, shipping methods and settings. It also lets you remove customers and check the prices a specific customer would pay.

What the Core API covers

AreaWhat you can do
Customer groupsList, create, update and delete customer groups, which can nest under a parent group
DiscountsList, create, update and delete discounts, and set the order in which they apply
ShippingList, create, update and delete the shipping methods offered at checkout
SettingsRead and update global settings, such as price list selection, payment methods and order validation, and override them per customer group
CustomersDelete a customer, and fetch the prices a customer would pay for a list of SKUs

Where other data comes from

Products and customers aren't created through the Core API. SparkLayer syncs them from your eCommerce platform — through a built-in integration such as Shopify or through Ignite for other platforms.

For other B2B data, use the dedicated API:

DataAPI
Price lists and pricesPricing API
Stock levels and stock locationsStock API
Orders, quotes and purchase transactions shown in My AccountPurchasing API
Carts and orders placed on behalf of a customerOrdering API
Files such as order attachmentsFiles API
Data sync status and errorsSync Logging API

See the API overview for base URLs and authentication.

Endpoints

Next steps

Was this page helpful?

Last updated

SparkLayer API

Overview of the SparkLayer REST APIs: what each API covers, base URLs for live and test, authentication, request format and which plans include access.

POSTGet an access token

Exchanges an API key's Client ID and Client Secret for an access token (the OAuth 2.0 client credentials grant). Send the credentials as JSON with `Content-Type: application/json`: the endpoint doesn't accept a form-encoded body, so standard OAuth 2.0 client libraries won't work. Send the token as `Authorization: Bearer <access_token>`, with the same `Site-Id` header, on every other request. Tokens are valid for 3,600 seconds (`expires_in`), and only for the Site ID and environment (live or test) they were issued for. There's no refresh token: cache the token and request a new one shortly before it expires. Create API keys in the SparkLayer Dashboard under **Settings > API**; deleting a key revokes its tokens. See [Authentication](https://docs.sparklayer.io/developers/authentication).