Skip to content

SparkLayer Ignite

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.
  • Ignite: With Ignite, SparkLayer calls endpoints that your service implements (the Ignite spec), and your service calls the SparkLayer APIs above for everything else.
  • 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

SparkLayer Ignite is a framework for connecting any eCommerce platform or CMS to SparkLayer, from the B2B self-service ordering experience on the storefront to SparkLayer's B2B pricing engine. You build a service, the Ignite integration, that SparkLayer calls to work with your platform.

Use cases

The most common use is alongside an eCommerce platform or content management system (CMS) that SparkLayer doesn't integrate with. For example, a platform may have very limited B2B functionality that isn't practical to build natively. Connecting it to SparkLayer through Ignite, for example with a custom application, adds the B2B features quickly.

To get access to Ignite, complete the application form (opens in a new tab). Our team reviews each application to check SparkLayer is a good match for the use case, both technically and strategically.

Before starting

These docs cover the principles and concepts you need to build an Ignite integration: connecting a platform, synchronising data and implementing the endpoints SparkLayer calls. To get familiar with how SparkLayer works first, read:

AreaNotes
The SparkLayer FrontendA JavaScript overlay that replaces specific parts of an eCommerce website with wholesale ordering features.
The SparkLayer DashboardThe web app where merchants manage every part of their SparkLayer setup.

Key principles

Understanding the data flow

Understanding how data flows between SparkLayer and your platform is central to building an integration. This diagram shows the key flows:

The key data flows between a platform, its SparkLayer Ignite integration and SparkLayer.

Platform

Integration

SparkLayer

Configuration
(sent from SparkLayer to the platform)
Platform connection
Products
Full product data(sent from the platform to SparkLayer)
Products
Orders
Order sync, plus shipments, refunds and cancellations(sent from the platform to SparkLayer)
Orders
Customers + addresses
Creation, updates and deletes(sent from the platform to SparkLayer)
Customers + addresses
Checkout / order
Tax and shipping calculations, checkouts and orders(sent from SparkLayer to the platform)
Checkout
Customers + additional attributes
Creating, updating and deleting a customer(sent from SparkLayer to the platform)
Customer sub-accounts
Logged-in customer
(sent from the platform to SparkLayer)
FE authentication
Validate token
(exchanged in both directions)

Platform connection

A platform connection links an eCommerce platform store to a SparkLayer site. SparkLayer calls two endpoints on your integration: one when a platform is connected, and one when it's disconnected. See Platform connection.

Data sync overview

SparkLayer needs data from the platform to work. A full sync runs when SparkLayer is first installed. After that, webhooks (or other platform events) should drive incremental updates, with the option to run a full sync again if there are issues. Log data sync issues with the Sync Logging API, so merchants can review them in the SparkLayer Dashboard (opens in a new tab). The data includes:

AreaDetails
Product dataSparkLayer needs a basic level of product data to be synced across for the frontend widgets to operate.
Customer dataSparkLayer needs a basic level of customer data to be synced across for the frontend widgets to operate.
Order dataSparkLayer needs order data to be synced across for the frontend widgets to show order data within the account section.
Store settingsSparkLayer needs to know the base currency of the store.

See Data sync.

Endpoints

SparkLayer calls these endpoints in real time, when a customer does something on the storefront. The endpoint reference gives the request and response bodies for each.

AreaDetails
Create, update and delete addressesCustomers manage their addresses in the My Account.
Fetch shipping and tax for an orderAs the customer goes through checkout in the My Cart, SparkLayer shows shipping rates and tax for the order.
Create and delete sub-account customersCustomers create and delete the customers who are their sub-accounts on the storefront.
Create a checkout for upfront ordersWhen a customer places an order that needs upfront payment through the platform (for example by credit card), SparkLayer sends them to the platform's checkout to pay. This can be the standard platform checkout, and doesn't need to include discounts and gift cards.
Create an order for orders paid offlineWhen a customer places an order that doesn't need payment at checkout, SparkLayer creates the order on the platform.

See the Endpoints overview.

Things to know

  • These docs don't cover billing or SparkLayer Dashboard logic.
  • SparkLayer supports a single storefront per SparkLayer environment.
  • SparkLayer supports simple option products only: complex bundles aren't supported.

Next steps

  1. Platform connection: handle a merchant connecting and disconnecting your platform.
  2. Authentication: verify the customers signed in to your platform.
  3. Data sync: sync products, customers, orders and settings to SparkLayer.
  4. Endpoints overview: every endpoint your integration implements.
Was this page helpful?

Last updated

Platform connection

Handle new and removed Ignite platform connections, whether started from a platform app store or the SparkLayer Dashboard, including redirect_url and full sync.