Skip to content
API reference

Pricing API

Steps for
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

With the Pricing API, your price list data comes directly from your backend system (such as an ERP, PIM, CRM or iPaaS), and each product SKU is then assigned to a price list in SparkLayer. The diagram shows how this works.

How price list data flows: price lists come from your backend system, are imported through the SparkLayer API, assigned to product SKUs and to customers, and the SparkLayer Frontend shows each signed-in customer their price.
  1. 1

    B2B pricing is managed in price lists that come from your backend system. Each B2B customer is assigned a price list, which gives them their own pricing when they sign in.

    Backend system
    (this flows forward)
    Price list 1Price list 2Price list 3
  2. 2

    Price lists are imported into SparkLayer through the SparkLayer API, each with a name, ID and currency code.

    SparkLayer
    API(this flows forward)
    Price list 1Price list 2Price list 3
  3. 3

    Price lists are then assigned to individual product SKUs. It's common for a SKU to have several price lists.

    Product A

    Price list 1Price list 2Price list 3

    Product B

    Price list 1Price list 2Price list 3

    Product C

    Price list 1Price list 2Price list 3

    Product D

    Price list 1Price list 2Price list 3
  4. 4

    Customers are also assigned a price list in SparkLayer, matching your backend system: Customer A sees Price list 1, Customer B sees Price list 2 and so on.

    Customer A
    (this flows forward)
    Price list 1
    Customer B
    (this flows forward)
    Price list 2
    Customer C
    (this flows forward)
    Price list 3
  5. 5

    When the customer signs in and visits a product page, the SparkLayer Frontend recognises them (and their price list) and shows their price. They can then add the product to their order.

    Example mug

    B2B price £2.99 RRP £9.99

    Product code MUG01 · Packs of 6

    6Add to order

Typical integration flow

The source system is the external system that sends the pricing data, such as your ERP. A typical sync:

  1. Fetch the price lists from the source system.
  2. Fetch the SparkLayer price lists with Get price lists. To fetch only the lists your integration manages, filter by source=integration.
  3. Create any price lists missing in SparkLayer with Create a price list. Set source to integration: the API uses integration for price lists from external systems, custom (the default) for lists set up in the Dashboard, and platform for lists from the eCommerce platform.
  4. Collect the prices for each price list from the source system and send them with Update pricing by price list.

The older GET /api/v1/price-lists endpoint is deprecated; use the v2 endpoint for new integrations.

The same process applies to customer-specific pricing: create a price list for the customer, with a reference that links it to them, and send prices to it.

To assign price lists to customers, use SparkLayer customer groups or assign them to customers directly. For direct assignment, see your platform's guide, such as Shopify metafields.

Data mapping

  • Price lists are linked to price list rules.
  • Prices are connected to product data by SKU, and each SKU's price belongs to a price list.
Price list data mapping: a price list links to price list rules and to prices; each price is linked to a product SKU.
Price list
(this flows forward)
Price list rule
(this flows forward)
Price
SKU(this is linked)
SKU

Checking price list data

To check which price lists a product's prices are in, use the price editor in the SparkLayer Dashboard, at Pricing,Price editor (opens in your SparkLayer Dashboard in a new tab).

Endpoints

Price Lists with Number of Manual Prices

Next steps

Was this page helpful?

Last updated

POSTCalculate a cart

Calculates the cart's totals, tax, available shipping methods and allowed payment methods, optionally for the shipping rate given in `shipping_rate_handle`. Returns `422` with the error code `cart-empty` if the cart has no items, or `cart-shipping-rate-handle-unavailable` if the SparkLayer shipping rate you chose isn't available for this cart.

GETList price lists

Returns every price list for the site as a single, unpaginated array (up to 25,000 price lists from all sources, ordered by name). This is the legacy version of this endpoint. For new integrations, use `GET /api/v2/price-lists`, which supports pagination, ordering and filtering by source.