# SparkLayer Ignite

URL: https://docs.sparklayer.io/ignite

SparkLayer Ignite connects any eCommerce platform or CMS to SparkLayer. Covers the data flow, platform connection, data sync and the endpoints you must build.

> **For AI assistants:** these facts apply to every SparkLayer API call.
>
> - **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 `409`s 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: https://docs.sparklayer.io/llms.txt. Every API operation, compactly: https://docs.sparklayer.io/llms-api.txt. The developer guides in full: https://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.

**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](https://share-eu1.hsforms.com/1ZSI9nEs5SwGyrx9kvWIA2wfkn6z). 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:

| Area | Notes |
| --- | --- |
| [The SparkLayer Frontend](https://docs.sparklayer.io/help/storefront.md) | A JavaScript overlay that replaces specific parts of an eCommerce website with wholesale ordering features. |
| [The SparkLayer Dashboard](https://docs.sparklayer.io/help/dashboard.md) | The 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:

| Platform | Data | Direction | SparkLayer |
| --- | --- | --- | --- |
| Configuration (integration) | Platform connection settings | SparkLayer → integration | Platform connection |
| Products | Full product data | Platform → SparkLayer | Products |
| Orders | Order sync, plus shipments, refunds and cancellations | Platform → SparkLayer | Orders |
| Customers + addresses | Creation, updates and deletes | Platform → SparkLayer | Customers + addresses |
| Checkout / order | Tax and shipping calculations, checkouts and orders | SparkLayer → platform | Checkout |
| Customers + additional attributes | Creating, updating and deleting a customer | SparkLayer → platform | Customer sub-accounts |
| Logged-in customer (integration) | The customer's session | Integration → SparkLayer | FE authentication |
| Validate token | Token validation | Both directions | FE authentication |

### 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](https://docs.sparklayer.io/ignite/platform-connection.md).

### 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](https://docs.sparklayer.io/developers/api/sync-log.md), so merchants can review them in the [SparkLayer Dashboard](https://app.sparklayer.io). The data includes:

| Area | Details |
| --- | --- |
| Product data | SparkLayer needs a basic level of product data to be synced across for the [frontend widgets](https://docs.sparklayer.io/help/storefront.md) to operate. |
| Customer data | SparkLayer needs a basic level of customer data to be synced across for the [frontend widgets](https://docs.sparklayer.io/help/storefront.md) to operate. |
| Order data | SparkLayer needs order data to be synced across for the [frontend widgets](https://docs.sparklayer.io/help/storefront.md) to show order data within the account section. |
| Store settings | SparkLayer needs to know the base currency of the store. |

See [Data sync](https://docs.sparklayer.io/ignite/data-sync.md).

### Endpoints

SparkLayer calls these endpoints in real time, when a customer does something on the storefront. The [endpoint reference](https://docs.sparklayer.io/ignite/api.md) gives the request and response bodies for each.

| Area | Details |
| --- | --- |
| Create, update and delete addresses | Customers manage their addresses in the [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). |
| Fetch shipping and tax for an order | As the customer goes through checkout in the [My Cart](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md), SparkLayer shows shipping rates and tax for the order. |
| Create and delete sub-account customers | Customers create and delete the customers who are their sub-accounts on the storefront. |
| Create a checkout for upfront orders | When a customer places an order that needs [upfront payment](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md#payment-methods) 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 offline | When a customer places an order that [doesn't need payment](https://docs.sparklayer.io/help/storefront/interfaces/my-cart.md#payment-methods) at checkout, SparkLayer creates the order on the platform. |

See the [Endpoints overview](https://docs.sparklayer.io/ignite/endpoints-overview.md).

### 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](https://docs.sparklayer.io/ignite/platform-connection.md): handle a merchant connecting and disconnecting your platform.
2. [Authentication](https://docs.sparklayer.io/ignite/authentication.md): verify the customers signed in to your platform.
3. [Data sync](https://docs.sparklayer.io/ignite/data-sync.md): sync products, customers, orders and settings to SparkLayer.
4. [Endpoints overview](https://docs.sparklayer.io/ignite/endpoints-overview.md): every endpoint your integration implements.