# SparkLayer Docs: Developers

> Everything needed to build on SparkLayer: the facts for calling the APIs, an index of every API operation, and every developer and Ignite guide in full (the API, JavaScript SDK, templates, data and Ignite integrations).

Source: https://docs.sparklayer.io/developers and https://docs.sparklayer.io/ignite. Each API operation's full reference (parameters, body, responses) is linked below; https://docs.sparklayer.io/llms-api.txt lists them with their parameters, and https://docs.sparklayer.io/llms.txt lists every page of the docs. Ready-made prompts for common jobs (shortened here to what to read and the steps) are at https://docs.sparklayer.io/developers/build-with-ai.md.

## Facts for building integrations

These apply to every call to the SparkLayer APIs. Use only what the docs and OpenAPI specs define.

- **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.

OpenAPI specs (index: https://docs.sparklayer.io/openapi/index.json; each is also published as `.json`):

- Core API: https://docs.sparklayer.io/openapi/core.yaml
- Ordering API: https://docs.sparklayer.io/openapi/ordering.yaml
- Pricing API: https://docs.sparklayer.io/openapi/pricing.yaml
- Purchasing API: https://docs.sparklayer.io/openapi/purchasing.yaml
- Stock API: https://docs.sparklayer.io/openapi/stock.yaml
- Files API: https://docs.sparklayer.io/openapi/files.yaml
- Sync Logging API: https://docs.sparklayer.io/openapi/sync-log.yaml
- Ignite endpoints: https://docs.sparklayer.io/openapi/ignite.yaml

## API operations

### Core API

Overview: https://docs.sparklayer.io/developers/api/core.md · OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

- `POST /api/auth/token` [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md)
- `DELETE /api/v1/customers/{lookupBy}/{id}` [Delete a customer](https://docs.sparklayer.io/developers/api/core/delete-a-customer.md)
- `POST /api/v1/fetch-customer-pricing` [Get customer-specific pricing](https://docs.sparklayer.io/developers/api/core/get-customer-specific-pricing.md)
- `GET /api/v1/customer-groups` [List customer groups](https://docs.sparklayer.io/developers/api/core/list-customer-groups.md)
- `POST /api/v1/customer-groups` [Create a customer group](https://docs.sparklayer.io/developers/api/core/new-customer-group.md)
- `DELETE /api/v1/customer-groups/{slug}` [Delete a customer group](https://docs.sparklayer.io/developers/api/core/delete-customer-group.md)
- `PATCH /api/v1/customer-groups/{slug}` [Update a customer group](https://docs.sparklayer.io/developers/api/core/update-customer-group.md)
- `GET /api/v1/discounts` [List discounts](https://docs.sparklayer.io/developers/api/core/list-of-discounts.md)
- `POST /api/v1/discounts` [Create a discount](https://docs.sparklayer.io/developers/api/core/create-a-discount.md)
- `PATCH /api/v1/set-discount-priorities` [Update discount priorities](https://docs.sparklayer.io/developers/api/core/update-discount-priorities.md)
- `GET /api/v1/discounts/{id}` [Get a discount](https://docs.sparklayer.io/developers/api/core/get-a-discount.md)
- `DELETE /api/v1/discounts/{id}` [Delete a discount](https://docs.sparklayer.io/developers/api/core/delete-a-discount.md)
- `PATCH /api/v1/discounts/{id}` [Update a discount](https://docs.sparklayer.io/developers/api/core/update-a-discount.md)
- `GET /api/v1/shipping-methods` [List shipping methods](https://docs.sparklayer.io/developers/api/core/list-of-shipping-methods.md)
- `POST /api/v1/shipping-methods` [Create a shipping method](https://docs.sparklayer.io/developers/api/core/create-a-shipping-method.md)
- `GET /api/v1/shipping-methods/{id}` [Get a shipping method](https://docs.sparklayer.io/developers/api/core/get-a-shipping-method.md)
- `DELETE /api/v1/shipping-methods/{id}` [Delete a shipping method](https://docs.sparklayer.io/developers/api/core/delete-a-shipping-method.md)
- `PATCH /api/v1/shipping-methods/{id}` [Update a shipping method](https://docs.sparklayer.io/developers/api/core/update-a-shipping-method.md)
- `GET /api/v1/settings` [List global settings](https://docs.sparklayer.io/developers/api/core/list-global-settings.md)
- `PATCH /api/v1/settings` [Update global settings](https://docs.sparklayer.io/developers/api/core/update-global-setting.md)
- `GET /api/v1/settings/{slug}` [List customer group settings](https://docs.sparklayer.io/developers/api/core/list-customer-group-settings.md)
- `PATCH /api/v1/settings/{slug}` [Update customer group settings](https://docs.sparklayer.io/developers/api/core/update-customer-group-setting.md)

### Ordering API

Overview: https://docs.sparklayer.io/developers/api/ordering.md · OpenAPI spec: https://docs.sparklayer.io/openapi/ordering.yaml

- `POST /api/v1/carts` [Create a cart](https://docs.sparklayer.io/developers/api/ordering/create-cart.md)
- `GET /api/v1/carts/{id}` [Get a cart](https://docs.sparklayer.io/developers/api/ordering/get-cart.md)
- `DELETE /api/v1/carts/{id}` [Delete a cart](https://docs.sparklayer.io/developers/api/ordering/delete-cart.md)
- `PATCH /api/v1/carts/{id}` [Update a cart](https://docs.sparklayer.io/developers/api/ordering/update-cart.md)
- `POST /api/v1/carts/{id}/complete` [Complete a cart](https://docs.sparklayer.io/developers/api/ordering/complete-cart.md)
- `POST /api/v1/carts/{id}/calculate` [Calculate a cart](https://docs.sparklayer.io/developers/api/ordering/calculate-cart.md)

### Pricing API

Overview: https://docs.sparklayer.io/developers/api/pricing.md · OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

- `GET /api/v1/price-lists` [List price lists](https://docs.sparklayer.io/developers/api/pricing/get-price-lists.md)
- `POST /api/v1/price-lists` [Create a price list](https://docs.sparklayer.io/developers/api/pricing/create-a-price-list.md)
- `GET /api/v1/price-lists/{slug}` [Get a price list](https://docs.sparklayer.io/developers/api/pricing/get-price-list.md)
- `DELETE /api/v1/price-lists/{slug}` [Delete a price list](https://docs.sparklayer.io/developers/api/pricing/delete-a-price-list.md)
- `PATCH /api/v1/price-lists/{slug}` [Update a price list](https://docs.sparklayer.io/developers/api/pricing/update-a-price-list.md)
- `GET /api/v2/price-lists` [List price lists (v2)](https://docs.sparklayer.io/developers/api/pricing/get-price-lists-v2.md)
- `GET /api/v1/price-lists/{slug}/pricing` [List prices in a price list](https://docs.sparklayer.io/developers/api/pricing/get-pricing-by-price-list.md)
- `PATCH /api/v1/price-lists/{slug}/pricing` [Update prices in a price list](https://docs.sparklayer.io/developers/api/pricing/update-pricing-by-price-list.md)
- `GET /api/v1/pricing/{sku}` [Get prices for a SKU](https://docs.sparklayer.io/developers/api/pricing/get-pricing-by-sku.md)
- `PATCH /api/v1/pricing/{sku}` [Update prices for a SKU](https://docs.sparklayer.io/developers/api/pricing/update-pricing-by-sku.md)
- `PATCH /api/v1/batch-update-pricing` [Update prices across price lists](https://docs.sparklayer.io/developers/api/pricing/update-pricing-for-multiple-price-lists.md)
- `POST /api/v1/calculate-pricing` [Calculate prices for SKUs](https://docs.sparklayer.io/developers/api/pricing/calculate-pricing.md)
- `GET /api/v2/price-lists-num-manual-prices` [List price lists with manual price counts](https://docs.sparklayer.io/developers/api/pricing/get-price-lists-with-manual-price-counts.md)

### Purchasing API

Overview: https://docs.sparklayer.io/developers/api/purchasing.md · OpenAPI spec: https://docs.sparklayer.io/openapi/purchasing.yaml

- `GET /api/v1/purchases/{lookupBy}/{identifier}` [Get a purchase](https://docs.sparklayer.io/developers/api/purchasing/get-purchase.md)
- `PUT /api/v1/purchases/{lookupBy}/{identifier}` [Create or update a purchase](https://docs.sparklayer.io/developers/api/purchasing/create-update-purchase.md)
- `DELETE /api/v1/purchases/{lookupBy}/{identifier}` [Delete a purchase](https://docs.sparklayer.io/developers/api/purchasing/delete-purchase.md)
- `GET /api/v1/purchases` [List purchases](https://docs.sparklayer.io/developers/api/purchasing/get-purchases.md)
- `GET /api/v1/purchases/{lookupBy}/{identifier}/history` [List purchase history](https://docs.sparklayer.io/developers/api/purchasing/get-purchase-history.md)
- `POST /api/v1/purchases/{lookupBy}/{identifier}/history` [Create a purchase history entry](https://docs.sparklayer.io/developers/api/purchasing/create-a-purchase-history-entry.md)
- `GET /api/v1/purchases/{lookupBy}/{identifier}/transactions` [List purchase transactions](https://docs.sparklayer.io/developers/api/purchasing/get-purchase-transactions.md)
- `PUT /api/v1/purchases/{lookupBy}/{identifier}/transactions` [Create or update a purchase transaction](https://docs.sparklayer.io/developers/api/purchasing/create-or-update-a-purchase-transaction.md)
- `GET /api/v1/store-currency` [Get the store currency](https://docs.sparklayer.io/developers/api/purchasing/get-store-currency.md)
- `PUT /api/v1/store-currency` [Update the store currency](https://docs.sparklayer.io/developers/api/purchasing/update-store-currency.md)
- `GET /api/v1/purchases/stats/order/sku` [Get a customer's SKU order stats](https://docs.sparklayer.io/developers/api/purchasing/get-order-stats-for-a-customer.md)

### Stock API

Overview: https://docs.sparklayer.io/developers/api/stock.md · OpenAPI spec: https://docs.sparklayer.io/openapi/stock.yaml

- `POST /api/v1/batch-fetch-stock` [Get stock levels for multiple SKUs](https://docs.sparklayer.io/developers/api/stock/get-stock-levels.md)
- `POST /api/v1/batch-update-stock` [Update stock levels for multiple SKUs](https://docs.sparklayer.io/developers/api/stock/update-stock-levels.md)
- `POST /api/v1/batch-delete-stock` [Delete stock levels for multiple SKUs](https://docs.sparklayer.io/developers/api/stock/delete-stock-levels.md)
- `GET /api/v1/stock-locations` [List stock locations](https://docs.sparklayer.io/developers/api/stock/list-stock-locations.md)
- `POST /api/v1/stock-locations` [Create a stock location](https://docs.sparklayer.io/developers/api/stock/create-a-stock-location.md)
- `GET /api/v1/stock-locations/{StockLocationID}` [Get a stock location](https://docs.sparklayer.io/developers/api/stock/get-a-stock-location.md)
- `DELETE /api/v1/stock-locations/{StockLocationID}` [Delete a stock location](https://docs.sparklayer.io/developers/api/stock/delete-a-stock-location.md)
- `PATCH /api/v1/stock-locations/{StockLocationID}` [Update a stock location](https://docs.sparklayer.io/developers/api/stock/update-a-stock-location.md)

### Files API

Overview: https://docs.sparklayer.io/developers/api/files.md · OpenAPI spec: https://docs.sparklayer.io/openapi/files.yaml

- `GET /api/v1/files` [Get multiple files](https://docs.sparklayer.io/developers/api/files/get-bulk-files.md)
- `POST /api/v1/files` [Create a file](https://docs.sparklayer.io/developers/api/files/create-a-new-file.md)
- `DELETE /api/v1/files` [Delete all files](https://docs.sparklayer.io/developers/api/files/delete-all-files.md)
- `POST /api/v1/search-files` [Search files by metadata](https://docs.sparklayer.io/developers/api/files/query-files-by-metadata.md)
- `GET /api/v1/files/{id}` [Get a file](https://docs.sparklayer.io/developers/api/files/get-a-file.md)
- `DELETE /api/v1/files/{id}` [Delete a file](https://docs.sparklayer.io/developers/api/files/delete-a-file.md)
- `PATCH /api/v1/files/{id}` [Update a file](https://docs.sparklayer.io/developers/api/files/update-a-file.md)
- `POST /api/v1/batch-delete-files` [Delete multiple files](https://docs.sparklayer.io/developers/api/files/delete-multiple-files.md)

### Sync Logging API

Overview: https://docs.sparklayer.io/developers/api/sync-log.md · OpenAPI spec: https://docs.sparklayer.io/openapi/sync-log.yaml

- `DELETE /api/v1/sync-log` [Delete all sync logs](https://docs.sparklayer.io/developers/api/sync-log/delete-a-stores-sync-logs.md)
- `GET /api/v1/sync-log/{integration}/{data_type}` [Get a sync status](https://docs.sparklayer.io/developers/api/sync-log/get-sync-logging-status.md)
- `PUT /api/v1/sync-log/{integration}/{data_type}` [Record a full sync](https://docs.sparklayer.io/developers/api/sync-log/update-sync-logs-with-a-full-sync.md)
- `PATCH /api/v1/sync-log/{integration}/{data_type}` [Record a partial sync](https://docs.sparklayer.io/developers/api/sync-log/update-sync-logs-with-a-partial-sync.md)
- `GET /api/v1/sync-log/{integration}/{data_type}/errors` [List sync errors](https://docs.sparklayer.io/developers/api/sync-log/get-sync-logging-status-errors.md)

### Ignite endpoints (your service implements these; SparkLayer calls them)

Overview: https://docs.sparklayer.io/ignite/api.md · OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

- `POST /v1/{siteEnv}/{siteId}` [Connect a platform](https://docs.sparklayer.io/ignite/api/new-platform-connection.md)
- `DELETE /v1/{siteEnv}/{siteId}` [Disconnect a platform](https://docs.sparklayer.io/ignite/api/remove-platform-connection.md)
- `PUT /v1/{siteEnv}/{siteId}/customers` [Create or update a customer](https://docs.sparklayer.io/ignite/api/create-update-a-customer.md)
- `POST /v1/{siteEnv}/{siteId}/sub-accounts` [Create a sub-account](https://docs.sparklayer.io/ignite/api/create-a-new-customer-sub-account.md)
- `DELETE /v1/{siteEnv}/{siteId}/sub-accounts/{customer_external_id}` [Delete a sub-account](https://docs.sparklayer.io/ignite/api/remove-a-customer-sub-account.md)
- `PATCH /v1/{siteEnv}/{siteId}/sub-accounts/{customer_external_id}` [Update a sub-account](https://docs.sparklayer.io/ignite/api/update-an-existing-customer-sub-account.md)
- `POST /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses` [Create a customer address](https://docs.sparklayer.io/ignite/api/create-a-new-customer-address.md)
- `PUT /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses/{customer_address_external_id}` [Update a customer address](https://docs.sparklayer.io/ignite/api/update-a-customer-address.md)
- `DELETE /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses/{customer_address_external_id}` [Delete a customer address](https://docs.sparklayer.io/ignite/api/remove-a-customer-address.md)
- `POST /v1/{siteEnv}/{siteId}/checkout/calculate` [Calculate tax and shipping](https://docs.sparklayer.io/ignite/api/calculate-tax-and-shipping.md)
- `POST /v1/{siteEnv}/{siteId}/checkout/complete` [Complete checkout](https://docs.sparklayer.io/ignite/api/complete-checkout.md)
- `GET /v1/{siteEnv}/{siteId}/sync/{syncDataType}` [List entities for a sync](https://docs.sparklayer.io/ignite/api/list-entities.md)
- `POST /v1/{siteEnv}/{siteId}/sync/{syncDataType}/{entityId}` [Fetch an entity](https://docs.sparklayer.io/ignite/api/fetch-entity.md)
- `POST /v1/{siteEnv}/{siteId}/status/{syncDataType}` [Trigger a data sync](https://docs.sparklayer.io/ignite/api/trigger-a-data-sync.md)
- `GET /v1/{siteEnv}/{siteId}/metafield-configuration` [Get metafield configuration](https://docs.sparklayer.io/ignite/api/get-metafield-configuration.md)
- `POST /v1/{siteEnv}/{siteId}/metafield-configuration/enable` [Enable a metafield](https://docs.sparklayer.io/ignite/api/enable-a-metafield.md)
- `POST /v1/{siteEnv}/{siteId}/authentication/verify` [Verify storefront authentication](https://docs.sparklayer.io/ignite/api/verify-authentication.md)

## Guides

# Developer documentation

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

Build on SparkLayer with the REST APIs, JavaScript SDK, storefront templates and Ignite, and make your first authenticated API call in a few minutes.

SparkLayer adds B2B ordering to the eCommerce platform you already use, such as Shopify. These pages are for developers who connect SparkLayer to other systems, or change how it works on a store.

New to SparkLayer? Start with [How SparkLayer connects](https://docs.sparklayer.io/developers/architecture.md). It explains which system holds which data, and that decides what you need to build.

## Choose what to build

- [REST APIs](https://docs.sparklayer.io/developers/api.md): Send price lists, stock levels and orders between your business systems, such as an ERP, and SparkLayer.
- [Frontend integration](https://docs.sparklayer.io/developers/frontend.md): Add SparkLayer to your store's theme, hide retail-only parts of the page from B2B customers, and match it to your design.
- [JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk.md): Write your own code to change how SparkLayer behaves on your store, or build a headless storefront.
- [Templates](https://docs.sparklayer.io/developers/templates.md): Change the invoice and quote PDFs, and the emails SparkLayer sends, with Liquid templates.
- [Ignite](https://docs.sparklayer.io/ignite.md): Use SparkLayer on an eCommerce platform it doesn't have a ready-made integration for.
- [Data and limits](https://docs.sparklayer.io/developers/data.md): Look up metafield keys for product, customer and order data, and the limits to design around.

Not sure which you need? [Building integrations](https://docs.sparklayer.io/developers/building-integrations.md) compares building on the API yourself with using a middleware partner, or [ask our support team](https://docs.sparklayer.io/help/support.md).

## Make your first API call

**Step 1.** **Check your plan**

API access is on the [Pro and Enterprise plans](https://www.sparklayer.io/pricing/).

**Step 2.** **Follow the quickstart**

The [quickstart](https://docs.sparklayer.io/developers/quickstart.md) takes you from no credentials to a working API call: create an API key, get an access token and call an endpoint.

**Step 3.** **Learn the rules every call follows**

How to [authenticate](https://docs.sparklayer.io/developers/authentication.md), what the APIs return when something goes wrong ([errors](https://docs.sparklayer.io/developers/errors.md)), and how long lists come back in pages ([pagination](https://docs.sparklayer.io/developers/pagination.md)).

**Step 4.** **Pick the APIs you need**

The [API overview](https://docs.sparklayer.io/developers/api.md) says what each API does and which ones most integrations use.

## Build with AI

These docs are written to work with AI assistants. Pick a ready-made prompt below, add a line about your setup, and open it in Claude or ChatGPT. Each prompt tells the assistant which pages to read and what a finished, production-ready result looks like. [Build with AI](https://docs.sparklayer.io/developers/build-with-ai.md) has every prompt, plus the docs MCP server and the OpenAPI specs.

### Sync prices from your ERP

Push price lists and SKU prices from your ERP or PIM into SparkLayer on a schedule.

Read:

- https://docs.sparklayer.io/developers/authentication.md: getting and using an access token
- https://docs.sparklayer.io/developers/api/pricing.md: how price lists and prices fit together
- https://docs.sparklayer.io/developers/api/pricing/get-price-lists-v2.md: listing existing price lists (paginated)
- https://docs.sparklayer.io/developers/api/pricing/create-a-price-list.md: creating missing price lists
- https://docs.sparklayer.io/developers/api/pricing/update-pricing-by-price-list.md: updating the prices in one price list
- https://docs.sparklayer.io/developers/api/pricing/update-pricing-for-multiple-price-lists.md: updating prices across price lists in one call
- https://docs.sparklayer.io/developers/api/sync-log.md: recording each sync so it shows in the SparkLayer Dashboard
- https://docs.sparklayer.io/developers/errors.md: error format and retries
- https://docs.sparklayer.io/developers/pagination.md: paging through price lists

Steps:

1. Read the price lists and prices (including any quantity price breaks) from my ERP.
2. Fetch every SparkLayer price list with `GET /api/v2/price-lists`, following the pagination.
3. Create any price list that exists in my ERP but not in SparkLayer with `POST /api/v1/price-lists`, as the Pricing API docs describe for price lists managed by an external system.
4. Send the prices for each price list with `PATCH /api/v1/price-lists/{slug}/pricing`, or several price lists at once with `PATCH /api/v1/batch-update-pricing`, matching products by SKU and keeping each request within the documented limits.
5. Record each run with the Sync Logging API: a full sync for a complete run, a partial sync for changes only.

### Keep stock levels in sync

Send stock levels per SKU and location from your ERP or WMS every few minutes.

Read:

- https://docs.sparklayer.io/developers/authentication.md: getting and using an access token
- https://docs.sparklayer.io/developers/api/stock.md: stock levels and stock locations
- https://docs.sparklayer.io/developers/api/stock/list-stock-locations.md: the stock locations SparkLayer knows about
- https://docs.sparklayer.io/developers/api/stock/update-stock-levels.md: updating stock for many SKUs in one call
- https://docs.sparklayer.io/developers/api/sync-log.md: recording each sync
- https://docs.sparklayer.io/developers/errors.md: error format and retries

Steps:

1. Read current stock levels per SKU (and per warehouse, if I have several) from my stock system.
2. Map my warehouses to SparkLayer stock locations from `GET /api/v1/stock-locations`, and tell me if any are missing rather than guessing.
3. Send the levels with `POST /api/v1/batch-update-stock`, matching products by SKU, in batches within the documented limits.
4. Record each run with the Sync Logging API.

### Send B2B orders to your ERP

Pick up new and updated B2B orders from SparkLayer and create them in your ERP.

Read:

- https://docs.sparklayer.io/developers/authentication.md: getting and using an access token
- https://docs.sparklayer.io/developers/api/purchasing.md: what a purchase is and how orders, quotes and carts differ
- https://docs.sparklayer.io/developers/api/purchasing/get-purchases.md: listing orders with filters
- https://docs.sparklayer.io/developers/api/purchasing/get-purchase.md: fetching one order in full
- https://docs.sparklayer.io/developers/pagination.md: offset paging through purchases
- https://docs.sparklayer.io/developers/errors.md: error format and retries

Steps:

1. List orders with `GET /api/v1/purchases`, filtered to orders updated since the last successful run (use the documented date filters, not my own), paging with `limit` and `offset`.
2. Fetch each order in full if the list response lacks fields I need, and map it to my ERP's sales order format, including lines, prices, tax, shipping and the customer.
3. Create the order in my ERP, or update it if it was already sent, keyed on the SparkLayer order ID so nothing is created twice.
4. Store the timestamp of the last order processed and resume from it on the next run.


---

# How SparkLayer connects

URL: https://docs.sparklayer.io/developers/architecture

How SparkLayer sits alongside your eCommerce platform and backend systems: B2B data syncs through the SparkLayer API while the Frontend adds wholesale features.

SparkLayer works alongside your eCommerce platform; it doesn't replace it. Your platform still runs your catalogue, your customers, checkout and orders. SparkLayer adds what B2B buyers need on top, such as their own prices, pack sizes and ordering rules.

How SparkLayer connects:

- **Backend:** B2B-specific data (price lists, product pack sizes, customer rules) comes from an ERP / CRM, a manual upload or an automatic sync, and is sent to the **SparkLayer Backend**, which stores it.
- **eCommerce platform** (e.g. Shopify): its core functions (order, catalogue and customer management, analytics, marketing and promotions, CMS) sync both ways with the **SparkLayer Connector**.
- **Website storefront:** core templates (homepage, collections, products, static pages, blog) work as normal. The **SparkLayer Frontend** overlays B2B widgets: product pricing, buy button, quick order form, checkout and ordering, and the My Account area.

## The three parts of SparkLayer

| Part | What it does |
| --- | --- |
| **Backend** | Stores your B2B data, such as price lists, pack sizes and customer rules. Your backend systems send it through the [SparkLayer API](https://docs.sparklayer.io/developers/api.md), or you add it with the import tools in the [Dashboard](https://docs.sparklayer.io/help/dashboard.md). |
| **Connector** | Keeps SparkLayer and your eCommerce platform in step, in both directions. Products and customers come in from your platform: see [Product and customer sync](https://docs.sparklayer.io/help/integrations/data-sync.md). |
| **Frontend** | Adds B2B features to your storefront, such as customer-specific prices, quick order and the My Account area. The rest of your site works as normal. See [Frontend integration](https://docs.sparklayer.io/developers/frontend.md). |

## What this means for your integration

- **Keep products and customers on your eCommerce platform.** SparkLayer reads them from there, so you don't send them to SparkLayer.
- **Send B2B data from the system that owns it.** Prices and stock usually live in your ERP, which is their [source of truth](https://docs.sparklayer.io/help/glossary.md#source-of-truth): send them to SparkLayer with the API, and change them in the ERP, not in SparkLayer.
- **No ready-made integration for your platform?** With [Ignite](https://docs.sparklayer.io/ignite.md), you build the Connector yourself.

## Next steps

- [SparkLayer API](https://docs.sparklayer.io/developers/api.md): What each API does, and which ones your integration needs.
- [Building integrations](https://docs.sparklayer.io/developers/building-integrations.md): Build the integration yourself, or use a middleware partner.
- [Data limitations](https://docs.sparklayer.io/developers/data/data-limitations.md): Recommended and hard limits on the data you send.
- [SparkLayer Ignite](https://docs.sparklayer.io/ignite.md): Connect SparkLayer to a platform without a ready-made integration.


---

# Building integrations

URL: https://docs.sparklayer.io/developers/building-integrations

Choose how to connect your ERP or CRM to SparkLayer: build a direct integration with the SparkLayer API or use a middleware partner such as an iPaaS.

If your B2B data lives in a backend system, such as an ERP or CRM, you can send it to SparkLayer automatically instead of keeping it up to date by hand. There are two ways to connect them.

## Choose how to connect

| Option | How it works | Who builds it | Choose it when |
| --- | --- | --- | --- |
| **Direct connection** | You build an integration between your backend system and SparkLayer with the [SparkLayer API](https://docs.sparklayer.io/developers/api.md). | Your developers, or an agency | You have developers, or you need full control over what syncs and when. |
| **Middleware connection** | A middleware tool you already use, such as an [iPaaS](https://docs.sparklayer.io/help/glossary.md#ipaas), passes the data between your backend system and SparkLayer. | Your middleware partner's team | Your systems already connect through middleware, and it supports SparkLayer. |

Either way, your backend system keeps talking to your eCommerce platform as it does today. Only the B2B data, such as price lists, pack sizes and payment terms, goes to SparkLayer.

How data flows between systems:

1. Your backend system (e.g. Brightpearl, Oracle NetSuite, Microsoft Dynamics, Cegid, SEKO, SAP, OrderWise) holds the B2B data that's typically synchronised: B2B pricing (e.g. price lists), product rules (e.g. pack sizing) and customer rules (e.g. payment terms).
2. It's integrated with both Shopify and SparkLayer, via a direct connection or a middleware connection.
3. Specific B2B data syncs to SparkLayer; product, customer and order data syncs to Shopify.
4. SparkLayer connects to Shopify and enables the B2B portal with your synchronised B2B data.

## Check for a ready-made integration

SparkLayer already integrates with many backend systems, so you may not need to build anything. See the [full list of integrations](https://www.sparklayer.io/integrations/index.html).

To talk through how SparkLayer works with your systems, contact our [support team](https://docs.sparklayer.io/help/support.md).

## Next steps

- [API quickstart](https://docs.sparklayer.io/developers/quickstart.md): make your first SparkLayer API request.
- [SparkLayer API](https://docs.sparklayer.io/developers/api.md): which APIs your integration needs.
- [SparkLayer Ignite](https://docs.sparklayer.io/ignite.md): connect SparkLayer to a platform without a ready-made integration.


---

# Quickstart

URL: https://docs.sparklayer.io/developers/quickstart

Make your first SparkLayer API call in about five minutes: create an API key in the Dashboard, request an access token and list your price lists.

This guide takes you from no credentials to a successful API call. You need a SparkLayer account on the [Pro or Enterprise plan](https://www.sparklayer.io/pricing/) and a terminal with `curl` (and [`jq`](https://jqlang.org), to read the token from the response).

> **Use the test environment first**
>
> If your account has [Test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md) set up, create your first key in the test environment and call `https://test.app.sparklayer.io`. Test and live hold separate data, so you can experiment without affecting your live store.

**Step 1.** **Create an API key**

In the SparkLayer Dashboard, go to **Settings > API** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/api)), or **SparkLayer Wholesale > Settings > API** in the Shopify app. For a test key, turn on **Test mode** in the left-hand menu first.

Select **Create new API Key**, enter a name such as `Quickstart`, and copy the three values shown:

| Value | Used as |
| --- | --- |
| Site ID | The `Site-Id` header on every request |
| Client ID | `client_id` when you request a token |
| Client Secret | `client_secret` when you request a token: shown once |

**Step 2.** **Save your credentials in your shell**

So the commands below run as they are, put your values in environment variables. For the test environment, set `SPARKLAYER_BASE_URL` to `https://test.app.sparklayer.io`.

```bash title="Terminal"
export SPARKLAYER_BASE_URL="https://app.sparklayer.io"
export SPARKLAYER_SITE_ID="<SITE_ID>"
export SPARKLAYER_CLIENT_ID="<CLIENT_ID>"
export SPARKLAYER_CLIENT_SECRET="<CLIENT_SECRET>"
```

**Step 3.** **Request an access token**

Exchange the client ID and secret for an access token. The request body is JSON, and the `Site-Id` header is required here too:

```bash title="Terminal"
curl -s -X POST "$SPARKLAYER_BASE_URL/api/auth/token" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"grant_type\": \"client_credentials\",
    \"client_id\": \"$SPARKLAYER_CLIENT_ID\",
    \"client_secret\": \"$SPARKLAYER_CLIENT_SECRET\"
  }"
```

The response contains your token, which is valid for one hour (`expires_in` is in seconds):

```json title="Response"
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "<ACCESS_TOKEN>"
}
```

To keep the token in a variable for the next step, run the same request through `jq`:

```bash title="Terminal"
export SPARKLAYER_TOKEN=$(curl -s -X POST "$SPARKLAYER_BASE_URL/api/auth/token" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$SPARKLAYER_CLIENT_ID\",\"client_secret\":\"$SPARKLAYER_CLIENT_SECRET\"}" \
  | jq -r .access_token)
```

**Step 4.** **Call an endpoint**

List your price lists with the [Pricing API](https://docs.sparklayer.io/developers/api/pricing/get-price-lists-v2.md), sending the token in the `Authorization` header and your Site ID in the `Site-Id` header:

```bash title="Terminal"
curl -s "$SPARKLAYER_BASE_URL/api/v2/price-lists?page=1&page_size=100" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "User-Agent: quickstart/1.0"
```

You get back a page of price lists, with an empty `data` list if your site has none yet:

```json title="Response"
{
  "data": [
    {
      "slug": "base-list",
      "name": "Base Price List",
      "currency_code": "GBP",
      "source": "custom",
      "tax_inclusive_display": false
    }
  ],
  "pagination": {
    "total": 1,
    "per_page": 100,
    "current_page": 1,
    "total_pages": 1
  }
}
```

## The same in code

The same two calls as a script you can build on. It reads the same environment variables.

**Node.js:**

Node.js 18 or later, with no dependencies:

```javascript title="quickstart.mjs"
const { SPARKLAYER_BASE_URL, SPARKLAYER_SITE_ID, SPARKLAYER_CLIENT_ID, SPARKLAYER_CLIENT_SECRET } =
  process.env;

const tokenResponse = await fetch(`${SPARKLAYER_BASE_URL}/api/auth/token`, {
  method: 'POST',
  headers: { 'Site-Id': SPARKLAYER_SITE_ID, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'client_credentials',
    client_id: SPARKLAYER_CLIENT_ID,
    client_secret: SPARKLAYER_CLIENT_SECRET,
  }),
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

const response = await fetch(`${SPARKLAYER_BASE_URL}/api/v2/price-lists?page=1&page_size=100`, {
  headers: {
    'Site-Id': SPARKLAYER_SITE_ID,
    Authorization: `Bearer ${access_token}`,
    'User-Agent': 'quickstart/1.0',
  },
});
if (!response.ok) throw new Error(`Request failed: ${response.status} ${await response.text()}`);
const { data, pagination } = await response.json();
console.log(`${pagination.total} price lists:`, data.map((list) => list.slug));
```

```bash title="Terminal"
node quickstart.mjs
```

**Python:**

Python 3.9 or later, with [`requests`](https://pypi.org/project/requests/):

```python title="quickstart.py"
import os

import requests

base_url = os.environ["SPARKLAYER_BASE_URL"]
site_id = os.environ["SPARKLAYER_SITE_ID"]

token_response = requests.post(
    f"{base_url}/api/auth/token",
    headers={"Site-Id": site_id},
    json={
        "grant_type": "client_credentials",
        "client_id": os.environ["SPARKLAYER_CLIENT_ID"],
        "client_secret": os.environ["SPARKLAYER_CLIENT_SECRET"],
    },
    timeout=30,
)
token_response.raise_for_status()
access_token = token_response.json()["access_token"]

response = requests.get(
    f"{base_url}/api/v2/price-lists",
    params={"page": 1, "page_size": 100},
    headers={
        "Site-Id": site_id,
        "Authorization": f"Bearer {access_token}",
        "User-Agent": "quickstart/1.0",
    },
    timeout=30,
)
response.raise_for_status()
body = response.json()
print(f"{body['pagination']['total']} price lists:", [p["slug"] for p in body["data"]])
```

```bash title="Terminal"
python quickstart.py
```

For a production integration, reuse the token until it's close to expiry instead of requesting one per call: see [Reuse the access token](https://docs.sparklayer.io/developers/authentication.md#reuse-the-access-token).

## If something goes wrong

| Response | What to check |
| --- | --- |
| `400` from `/api/auth/token` | The `Site-Id` and `Content-Type: application/json` headers are set, and the body includes all three fields |
| `401` from `/api/auth/token` | The client ID and secret are correct and belong to the environment you're calling: live keys only work with `https://app.sparklayer.io`, test keys with `https://test.app.sparklayer.io` |
| `401` or `403` from an API endpoint | The `Authorization` header is `Bearer ` followed by the token, the token is less than an hour old, and you're sending the same `Site-Id` and base URL you requested the token with |
| `jq: command not found` | Install `jq`, or copy `access_token` from the response by hand: `export SPARKLAYER_TOKEN="<ACCESS_TOKEN>"` |

See [Errors](https://docs.sparklayer.io/developers/errors.md) for the error format and every status code.

## Next steps

- [Build with AI](https://docs.sparklayer.io/developers/build-with-ai.md): Ready-made prompts for syncing prices, stock and orders
- [Authentication](https://docs.sparklayer.io/developers/authentication.md): Environments, token reuse and authentication errors
- [API overview](https://docs.sparklayer.io/developers/api.md): Find the APIs your integration needs

Every endpoint page in the API reference also has a playground: enter your token and Site ID to try requests from your browser.


---

# Authentication

URL: https://docs.sparklayer.io/developers/authentication

Authenticate with the SparkLayer APIs using OAuth 2.0 client credentials: request a Bearer token from /api/auth/token and send it with your Site-Id header.

Every request to the SparkLayer APIs needs an access token. Getting one takes three steps:

1. Create an API key in the SparkLayer Dashboard.
2. Swap the key's client ID and secret for an access token, which lasts an hour.
3. Send the token with every request.

This is the standard OAuth 2.0 client credentials flow.

For a step-by-step first call, see the [quickstart](https://docs.sparklayer.io/developers/quickstart.md).

## Environments

Each SparkLayer account has a live environment and, on plans with [Test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md), a test environment. The host you call selects the environment:

| Environment | Base URL |
| --- | --- |
| Live | `https://app.sparklayer.io` |
| Test | `https://test.app.sparklayer.io` |

The environments hold separate data and separate API keys. A key created while the Dashboard is in Test mode only works against the test base URL, and a key created in live mode only works against the live base URL.

## Create an API key

**Step 1.** **Open the API settings**

In the SparkLayer Dashboard, go to **Settings > API** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/api)), or **SparkLayer Wholesale > Settings > API** in the Shopify app. Turn on **Test mode** first if you want a key for the test environment.

**Step 2.** **Create a key**

Select **Create new API Key** and give the key a name that identifies the integration using it.

**Step 3.** **Copy the credentials**

Copy the **Site ID**, **Client ID** and **Client Secret**. The client secret is only shown once, so store it securely — for example in your integration's secrets manager.

Deleting a key in the Dashboard also revokes every access token issued for it.

## Request an access token

Send a `POST` request to `/api/auth/token` with your Site ID in the `Site-Id` header and your credentials in a JSON body. The token endpoint only accepts `Content-Type: application/json`:

```bash
curl -X POST https://app.sparklayer.io/api/auth/token \
  -H "Site-Id: <SITE_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>"
  }'
```

| Field | Value |
| --- | --- |
| `grant_type` | Always `client_credentials` |
| `client_id` | The Client ID shown when you created the key |
| `client_secret` | The Client Secret shown when you created the key |

If the credentials are valid, you receive an access token:

```json
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "<ACCESS_TOKEN>"
}
```

| Field | Description |
| --- | --- |
| `token_type` | Always `Bearer` |
| `expires_in` | Seconds until the token expires: tokens are valid for 1 hour |
| `access_token` | The token to send in the `Authorization` header |

A token only works with the Site ID and environment it was issued for. No refresh token is issued: when a token expires, request a new one with the same credentials.

> **Standard OAuth libraries won't work as they are**
>
> The token request is JSON with a `Site-Id` header, not the form-encoded body most OAuth 2.0 client libraries send. Request the token with a plain HTTP call, as below, or configure your library to send JSON and the extra header.

## Call the API

Send the token in the `Authorization` header, together with the `Site-Id` header, on every request:

```bash
curl "https://app.sparklayer.io/api/v2/price-lists" \
  -H "Site-Id: <SITE_ID>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "User-Agent: acme-erp-sync/1.2"
```

| Header | Value |
| --- | --- |
| `Site-Id` | Your Site ID |
| `Authorization` | `Bearer <ACCESS_TOKEN>` |
| `Content-Type` | `application/json` for requests with a body |

> **Set a User-Agent**
>
> Set a `User-Agent` header that identifies your integration, such as `acme-erp-sync/1.2`. It helps our support team find your requests if you need help debugging an issue.

## Reuse the access token

Request a token once and reuse it for every call until it's close to expiry, rather than requesting one per call. These small helpers do that, and fetch a new token when one is rejected:

**Node.js:**

```javascript title="sparklayer.mjs"
const { SPARKLAYER_BASE_URL, SPARKLAYER_SITE_ID, SPARKLAYER_CLIENT_ID, SPARKLAYER_CLIENT_SECRET } =
  process.env;

let token = null; // { value, expiresAt }

async function getToken() {
  // reuse the token until a minute before it expires
  if (token && Date.now() < token.expiresAt - 60_000) return token.value;
  const response = await fetch(`${SPARKLAYER_BASE_URL}/api/auth/token`, {
    method: 'POST',
    headers: { 'Site-Id': SPARKLAYER_SITE_ID, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'client_credentials',
      client_id: SPARKLAYER_CLIENT_ID,
      client_secret: SPARKLAYER_CLIENT_SECRET,
    }),
  });
  if (!response.ok) throw new Error(`Token request failed: ${response.status}`);
  const body = await response.json();
  token = { value: body.access_token, expiresAt: Date.now() + body.expires_in * 1000 };
  return token.value;
}

/** Calls a SparkLayer API path, e.g. sparklayer('/api/v2/price-lists'). */
export async function sparklayer(path, init = {}, retried = false) {
  const response = await fetch(`${SPARKLAYER_BASE_URL}${path}`, {
    ...init,
    headers: {
      'Site-Id': SPARKLAYER_SITE_ID,
      Authorization: `Bearer ${await getToken()}`,
      'User-Agent': 'acme-erp-sync/1.2',
      ...(init.body ? { 'Content-Type': 'application/json' } : {}),
      ...init.headers,
    },
  });
  if (response.status === 401 && !retried) {
    token = null; // the token was rejected: get a new one and try once more
    return sparklayer(path, init, true);
  }
  return response;
}
```

**Python:**

```python title="sparklayer.py"
import os
import time

import requests

BASE_URL = os.environ["SPARKLAYER_BASE_URL"]
SITE_ID = os.environ["SPARKLAYER_SITE_ID"]
_token = {"value": None, "expires_at": 0.0}

def get_token() -> str:
    # reuse the token until a minute before it expires
    if _token["value"] and time.time() < _token["expires_at"] - 60:
        return _token["value"]
    response = requests.post(
        f"{BASE_URL}/api/auth/token",
        headers={"Site-Id": SITE_ID},
        json={
            "grant_type": "client_credentials",
            "client_id": os.environ["SPARKLAYER_CLIENT_ID"],
            "client_secret": os.environ["SPARKLAYER_CLIENT_SECRET"],
        },
        timeout=30,
    )
    response.raise_for_status()
    body = response.json()
    _token.update(value=body["access_token"], expires_at=time.time() + body["expires_in"])
    return _token["value"]

def sparklayer(method: str, path: str, retried: bool = False, **kwargs) -> requests.Response:
    """Calls a SparkLayer API path, e.g. sparklayer("GET", "/api/v2/price-lists")."""
    headers = {
        "Site-Id": SITE_ID,
        "Authorization": f"Bearer {get_token()}",
        "User-Agent": "acme-erp-sync/1.2",
        **kwargs.pop("headers", {}),
    }
    response = requests.request(method, f"{BASE_URL}{path}", headers=headers, timeout=60, **kwargs)
    if response.status_code == 401 and not retried:
        _token["value"] = None  # the token was rejected: get a new one and try once more
        return sparklayer(method, path, retried=True, **kwargs)
    return response
```

For retries on other errors, see [Retrying requests](https://docs.sparklayer.io/developers/errors.md#retrying-requests).

## Authentication errors

If authentication fails, the API responds with a JSON error body. See [Errors](https://docs.sparklayer.io/developers/errors.md) for the format and every status code.

| Status | When |
| --- | --- |
| `400` | The token request is missing the `Site-Id` header, a required field or `Content-Type: application/json` |
| `401` | The client ID or secret is wrong, or the access token is missing, invalid or expired |
| `401` or `403` | The access token was issued for a different Site ID or environment. The Pricing and Purchasing APIs also return `403` when the `Authorization` header is missing |


---

# Errors

URL: https://docs.sparklayer.io/developers/errors

HTTP status codes the SparkLayer APIs return, the JSON error body and its fields, validation error details, and which errors you can safely retry.

The SparkLayer APIs use standard HTTP status codes: `2xx` for success, `4xx` when the request needs fixing, and `5xx` when something went wrong on SparkLayer's side. Most errors include a JSON body that explains the problem.

## Error body

Error bodies follow the [RFC 7807 problem details](https://www.rfc-editor.org/rfc/rfc7807) format:

```json
{
  "title": "invalid-request-contents",
  "status": 400,
  "detail": "Unable to validate request contents",
  "errors": [
    {
      "code": "keyword-mismatch",
      "message": "<what is wrong with the value>",
      "property": "customer_id"
    }
  ]
}
```

| Field | Description |
| --- | --- |
| `title` | A short identifier for the type of problem, such as `invalid-request-contents` or `resource-not-found` |
| `status` | The HTTP status code, repeated for convenience |
| `detail` | A human-readable explanation. Use it for logging and debugging, not to drive your integration's logic |
| `errors` | Optional. A list of individual problems, each with a machine-readable `code`, a `message` and, where relevant, the `property` it applies to |

Some APIs also include `"type": "about:blank"`. Treat the status code as the primary signal, `title` and `errors[].code` as more specific detail, and ignore fields you don't recognise.

> **Differences between APIs**
>
> The APIs are separate services, so some responses differ in detail:
>
> - Errors are `application/problem+json`, except the cart's **Calculate** and **Complete** validation errors (`422`), which are plain `application/json` with their own `cart-error` and `cart-validation-errors` shapes.
> - Invalid price updates sent to the [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md) (for example with **Update prices in a price list**) return a `400` whose body is a list of `{ "line", "field", "message" }` objects, so you can match each problem to a row of your JSON array or CSV file.
> - Some responses, such as a `404` for an unknown route, a `405`, a `415` or an unexpected `500`, can have an empty body.
> - The endpoint pages in the API reference list the responses each operation returns.

## Status codes

| Status | Meaning | What to do |
| --- | --- | --- |
| `200`, `201`, `204` | Success. `204` responses have no body | — |
| `207` | Partial success: some items in the request couldn't be processed, and each affected item carries an error. Returned by **Get customer-specific pricing** | Check each item for an error |
| `400` | The request is invalid: the body, parameters or headers (including `Site-Id`) don't match the API's schema, a required value is missing, or the request breaks a business rule | Fix the request using `detail` and `errors`. Don't retry it unchanged |
| `401` | The access token is missing, malformed or expired, or was issued for a different site or environment. On `/api/auth/token`, the client ID or secret is wrong | Request a new access token, then retry. See [Authentication](https://docs.sparklayer.io/developers/authentication.md) |
| `403` | The request isn't allowed. The Pricing and Purchasing APIs also return `403` when the `Authorization` header is missing, or the token was issued for a different site or environment | Check the `Authorization` and `Site-Id` headers, and that you're using credentials for the right environment |
| `404` | The resource or route doesn't exist | Check the ID, slug or `lookupBy` value and the URL |
| `405` | The endpoint exists but doesn't support the HTTP method | Check the method in the API reference |
| `409` | The request conflicts with existing data — for example a duplicate external ID, a newer version of the record already exists, or another update to the same data was running at the same time | Fetch the current state, resolve the conflict and retry |
| `410` | The resource is gone — for example a file that failed its checks after upload | Don't retry. Upload the file again |
| `415` | The `Content-Type` header isn't supported by the endpoint | Send `Content-Type: application/json` (the Pricing API also accepts `text/csv` on some endpoints) |
| `422` | The Ordering API can't process the cart — for example it's empty, or it has validation errors when you try to complete it | See [Cart errors](#cart-errors) |
| `500` | An unexpected error on SparkLayer's side | Retry with exponential backoff. If it persists, [contact support](https://docs.sparklayer.io/help/support.md) with the request details |
| `502`, `503`, `504` | The service is temporarily unavailable or took too long to respond | Retry with exponential backoff |

## Authentication errors

Errors from `/api/auth/token`, and errors caused by a missing or invalid token on the Core and Ordering APIs, use [OAuth 2.0 error codes](https://www.rfc-editor.org/rfc/rfc6749#section-5.2) as the `title`:

```json
{
  "title": "invalid_client",
  "status": 401,
  "detail": "Client authentication failed"
}
```

| `title` | Status | Cause |
| --- | --- | --- |
| `invalid_client` | `401` | The client ID or secret is wrong, the key has been deleted, or it belongs to the other environment |
| `invalid_request` | `400` | A required field, such as `client_secret`, is missing |
| `unsupported_grant_type` | `400` | `grant_type` isn't `client_credentials` |
| `access_denied` | `401` | The `Authorization` header is missing, or the token is invalid, expired or for another site or environment |

The Pricing, Purchasing, Stock, Sync Logging and Files APIs return a `401` or `403` problem body with a `detail` explaining why the token was rejected.

## Validation errors

When a request doesn't match the API's schema, the response is a `400` with details of each problem in `errors`. On the Core and Ordering APIs, and for most requests to the Pricing API, the `title` is `invalid-request-contents`. The Core and Ordering APIs use these codes:

| `code` | Cause |
| --- | --- |
| `keyword-mismatch` | A value breaks a schema rule, such as a type, format or length. `property` points to it |
| `body-mismatch` | The body isn't valid JSON or doesn't match the expected shape |
| `headers-mismatch` | A required header, such as `Site-Id` or `Content-Type`, is missing or invalid |
| `parameters-mismatch` | A path or query parameter is invalid, such as an unsupported `lookupBy` value |
| `path-mismatch` | The path doesn't match the endpoint |
| `missing-param` | A required value is missing |
| `resource-already-exists` | A value that must be unique, such as a slug, is already in use |
| `resource-id-not-found` | An ID or slug in the request doesn't match an existing resource |
| `resource-id-invalid` | An ID isn't in the expected format |
| `resource-in-use` | The resource can't be deleted because something else uses it |

The Purchasing, Stock, Sync Logging and Files APIs describe schema problems in `detail` instead.

## Cart errors

The [Ordering API](https://docs.sparklayer.io/developers/api/ordering.md) returns `422` when it can't process a cart. The `title` tells you which kind of problem it is:

- `cart-error`: `errors` lists codes such as `cart-empty`, `cart-customer-not-found`, `cart-shipping-rate-handle-unavailable` or `cart-payment-method-unavailable`.
- `cart-validation-errors`: returned by **Complete a cart** when the cart has validation errors you haven't chosen to ignore. `errors.validation_error_types` lists them. Fix the cart, or list the types you accept in `ignore_validation_errors`, and try again.

## Retrying requests

- Retry `5xx` responses and `409` conflicts caused by concurrent updates, using exponential backoff.
- On a `401`, request a new access token once and retry. If it fails again, check your credentials rather than retrying.
- Don't retry other `4xx` responses without changing the request.
- `PUT` requests that create or replace a record, such as **Create or update a purchase**, are safe to repeat. Before retrying a `POST` that creates something, check whether the first attempt succeeded.

## Rate limits

SparkLayer doesn't publish fixed rate limits. Design your integration to be gentle and to recover:

- Send changes in batches using the bulk endpoints (for example **Update prices across price lists** and **Update stock levels for multiple SKUs**) rather than one request per SKU.
- Run requests one after another, or with a small number in parallel.
- No SparkLayer API returns `429 Too Many Requests` today. If you ever receive one, wait before retrying: use the `Retry-After` header if the response has one, otherwise back off exponentially.


---

# Pagination

URL: https://docs.sparklayer.io/developers/pagination

Page through large result sets in the SparkLayer APIs: page-based pagination for price lists, offset paging for purchases, and which lists return everything.

Most SparkLayer list endpoints return every matching record in a single response. Two endpoint families paginate, each with its own pattern.

## Page-based: price lists

`GET /api/v2/price-lists` and `GET /api/v2/price-lists-num-manual-prices` in the [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md) return results one page at a time.

| Query parameter | Default | Description |
| --- | --- | --- |
| `page` | `1` | The page to return |
| `page_size` | `100` | Records per page, up to `250` |
| `order_by` | `name:asc` | Sort field and direction: `name`, `created_at` or `updated_at`, followed by `:asc` or `:desc` |

The response wraps the records in `data`, with a `pagination` object:

```json
{
  "data": [ … ],
  "pagination": {
    "total": 312,
    "per_page": 100,
    "current_page": 1,
    "total_pages": 4
  }
}
```

Request pages until `current_page` equals `total_pages`:

```bash
curl "https://app.sparklayer.io/api/v2/price-lists?page=2&page_size=100" \
  -H "Site-Id: <SITE_ID>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

> **Use v2 for price lists**
>
> `GET /api/v1/price-lists` is the older, unpaginated version of this endpoint: it returns up to 25,000 price lists in one array. Use `GET /api/v2/price-lists` for new integrations.

## Offset-based: purchases

`GET /api/v1/purchases` in the [Purchasing API](https://docs.sparklayer.io/developers/api/purchasing.md) uses a limit and an offset.

| Query parameter | Default | Description |
| --- | --- | --- |
| `limit` | Not set | Maximum number of purchases to return, from `1` to `500`. Always set it. |
| `offset` | `0` | Number of purchases to skip |
| `order_by` | `created_at` | Field to sort by, always newest first: `created_at`, `updated_at`, `placed_at`, `calculated_submitted_at` or `shipping_requested_date` |

The response is a plain array with no total count. To fetch every purchase, increase `offset` by `limit` after each request, and stop when a response contains fewer than `limit` purchases:

```bash
curl "https://app.sparklayer.io/api/v1/purchases?type=order&limit=500&offset=500" \
  -H "Site-Id: <SITE_ID>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

Keep `order_by` and any filters the same for every page. Records created or updated while you're paging can shift between pages, so use a date filter such as `dates[last_updated][gte]` for incremental syncs.

## Endpoints that aren't paginated

Other list endpoints return all matching records in one response, including the Core API's customer groups, discounts, shipping methods and settings, and the Stock API's stock locations. A few have a fixed upper limit:

- **List sync errors** in the [Sync Logging API](https://docs.sparklayer.io/developers/api/sync-log.md) returns at most 5,000 errors.
- **List price lists** (v1) returns at most 25,000 price lists.


---

# SparkLayer API

URL: https://docs.sparklayer.io/developers/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.

The SparkLayer API is a set of REST APIs that connect your backend systems, such as an ERP, CRM or [iPaaS](https://docs.sparklayer.io/help/glossary.md#ipaas), to SparkLayer. Use them to send B2B data like price lists and stock levels, keep order history in step, and manage how customers buy.

> **Plan requirement**
>
> API access is available on the [Pro and Enterprise plans](https://www.sparklayer.io/pricing/).

## Which APIs you need

Most integrations need only one or two of these APIs.

- **On a platform SparkLayer integrates with, such as [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md)?** SparkLayer already gets your products and customers from the platform. Start with the Pricing API, and add the Stock and Purchasing APIs if your ERP holds stock levels and order history.
- **On a platform SparkLayer doesn't integrate with?** Use [Ignite](#ignite) to connect it.

If you're not sure which approach suits your integration, [contact our support team](https://docs.sparklayer.io/help/support.md) to talk it through.

## The APIs

| API | Use it to |
| --- | --- |
| [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md) | Create price lists, set prices by SKU and calculate the price a customer pays |
| [Stock API](https://docs.sparklayer.io/developers/api/stock.md) | Read, update and delete stock levels by SKU, and manage stock locations |
| [Purchasing API](https://docs.sparklayer.io/developers/api/purchasing.md) | Keep the orders, quotes and carts customers see in My Account, with their history and payments |
| [Ordering API](https://docs.sparklayer.io/developers/api/ordering.md) | Build a cart for a customer, price it, and place it as an order on your eCommerce platform |
| [Core API](https://docs.sparklayer.io/developers/api/core.md) | Manage customer groups, discounts, shipping methods and settings, delete customers, and look up a customer's prices |
| [Files API](https://docs.sparklayer.io/developers/api/files.md) | Upload and download files, such as the attachments customers add to orders |
| [Sync Logging API](https://docs.sparklayer.io/developers/api/sync-log.md) | Record when each data sync ran, and which records failed and why |

## Base URLs

| Environment | Base URL |
| --- | --- |
| Live | `https://app.sparklayer.io` |
| Test | `https://test.app.sparklayer.io` |

All the APIs share the same base URL. Live and test hold separate data and use separate API keys: see [Test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md).

## Authentication

The APIs use the OAuth 2.0 client credentials flow:

1. Create an API key in the Dashboard, at **Settings > API** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/api)), or **SparkLayer Wholesale > Settings > API** in the Shopify app.
2. Exchange its client ID and secret for an access token at `POST /api/auth/token`. Tokens are valid for one hour.
3. Send the token as `Authorization: Bearer <ACCESS_TOKEN>`, with your Site ID in the `Site-Id` header, on every request.

See [Authentication](https://docs.sparklayer.io/developers/authentication.md) for the full flow, or the [quickstart](https://docs.sparklayer.io/developers/quickstart.md) to make your first call.

## Requests and responses

- Request and response bodies are JSON. Send `Content-Type: application/json` with any request that has a body.
- Send a `User-Agent` header that identifies your integration, so our support team can find your requests.
- Errors return an HTTP status code and a JSON body describing the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).
- Some list endpoints return results in pages: see [Pagination](https://docs.sparklayer.io/developers/pagination.md).

## Ignite

[Ignite](https://docs.sparklayer.io/ignite.md) connects SparkLayer to an eCommerce platform it doesn't have a ready-made integration for. It works the other way round from the APIs above: instead of your code calling SparkLayer, SparkLayer calls a service you build. That service answers [SparkLayer's requests](https://docs.sparklayer.io/ignite/api.md), for example to create customers, work out tax and shipping, complete checkout and sync data from your platform.

## Next steps

- [Quickstart](https://docs.sparklayer.io/developers/quickstart.md): make your first API request.
- [Authentication](https://docs.sparklayer.io/developers/authentication.md): handle tokens and token expiry.
- [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md): the API most integrations start with.


---

# Core API

URL: https://docs.sparklayer.io/developers/api/core

Manage customer groups, discounts, shipping methods and settings with the Core API, delete customers and look up customer-specific pricing.

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

| Area | What you can do |
| --- | --- |
| Customer groups | List, create, update and delete customer groups, which can nest under a parent group |
| Discounts | List, create, update and delete discounts, and set the order in which they apply |
| Shipping | List, create, update and delete the shipping methods offered at checkout |
| Settings | Read and update global settings, such as price list selection, payment methods and order validation, and override them per customer group |
| Customers | Delete 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](https://docs.sparklayer.io/help/platforms/shopify.md) or through [Ignite](https://docs.sparklayer.io/ignite.md) for other platforms.

For other B2B data, use the dedicated API:

| Data | API |
| --- | --- |
| Price lists and prices | [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md) |
| Stock levels and stock locations | [Stock API](https://docs.sparklayer.io/developers/api/stock.md) |
| Orders, quotes and purchase transactions shown in My Account | [Purchasing API](https://docs.sparklayer.io/developers/api/purchasing.md) |
| Carts and orders placed on behalf of a customer | [Ordering API](https://docs.sparklayer.io/developers/api/ordering.md) |
| Files such as order attachments | [Files API](https://docs.sparklayer.io/developers/api/files.md) |
| Data sync status and errors | [Sync Logging API](https://docs.sparklayer.io/developers/api/sync-log.md) |

See the [API overview](https://docs.sparklayer.io/developers/api.md) for base URLs and authentication.

## Endpoints

_Every operation is listed under "API operations" at the top of this file._

## Next steps

- [Authentication](https://docs.sparklayer.io/developers/authentication.md): get an access token for your requests.
- [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md): sync price lists and prices.


---

# Ordering API

URL: https://docs.sparklayer.io/developers/api/ordering

Create, update, calculate and complete carts with the Ordering API to place orders for customers, check their pricing first and handle validation errors.

The Ordering API lets you create SparkLayer carts on behalf of your customers and complete them as orders on your connected eCommerce platform — for example to place orders from an external system or for drop shipping. Carts use the same pricing, validation, ordering rules and checkout logic as the SparkLayer cart your customers use, except that upfront payment methods aren't available for carts created through the API.

> **Beta**
>
> The Ordering API is in beta. If you'd like to use it, email [support@sparklayer.io](mailto:support@sparklayer.io) and our team will help you get started.

The API reference below gives full endpoint and schema details. This guide covers checking customer-specific pricing, the cart and order lifecycle, and how validation works.

## Customer-specific pricing lookup

The [Get customer-specific pricing](https://docs.sparklayer.io/developers/api/core/get-customer-specific-pricing.md) endpoint is part of the Core API. Use it before creating a cart to check pricing and price breaks for validation or user feedback.

It calculates real-time pricing for one or more SKUs in the context of a specific customer. It returns per-line-item unit prices, line totals, and quantity price breaks, accounting for the customer's assigned price lists and any customer-level discount percentage.

### Price calculation

SparkLayer looks up the customer's assigned price lists and uses those to calculate accurate pricing for each requested product. This includes:

- **Quantity price breaks** — the price adjusts based on how many units are being ordered
- **Variant aggregation** — if your store is configured to apply price breaks across variants, quantities across sizes or colours of the same product are combined when determining the price tier. For example, ordering 5× size M and 5× size L could unlock the 10-unit price break for both.
- **Customer discounts** — any discount assigned to the customer is applied on top of the list price

Each product in the response includes the unit price, line total, and a full breakdown of available quantity price breaks. All prices are returned as net values.

### Potential issues

- **Partial pricing failure** — if any product can't be priced, the response status is `207`: affected line items include an error with null pricing data, and successfully priced items are returned alongside them.
- **Invalid request** — a `400` is returned if the request is malformed, the customer doesn't exist, or the customer has no price lists configured.

## Order lifecycle

Every order starts as a cart for a customer, and goes through four steps:

1. [Create a cart](#1-create-an-empty-cart) for the customer.
2. [Update the cart](#2-update-the-cart) with line items and order details, and review any validation errors.
3. [Calculate the cart](#3-calculate-the-cart) to get totals and the available shipping and payment methods. Calculate again with your chosen shipping rate to confirm the totals.
4. [Complete the cart](#4-complete-the-cart) with the shipping rate and payment method to place the order.

## 1. Create an empty cart

[Create a cart](https://docs.sparklayer.io/developers/api/ordering/create-cart.md) for the customer you're placing the order for. Identify the customer with `customer_id` and `customer_lookup_by`: `sparklayer` (the customer's SparkLayer ID), `platform` (the ID from your eCommerce platform) or `email`.

A new cart is empty. It holds all the order information, including line items, quantities and the shipping address. The response includes a `cart_id`: use it for every later request about the cart.

## 2. Update the cart

[Update the cart](https://docs.sparklayer.io/developers/api/ordering/update-cart.md) with the information the order needs:

- Line items and their quantities
- The shipping address (`shipping_address_id`), or a `temporary_shipping_address`
- The customer reference, PO number, requested shipping date and custom fields

Each update replaces the cart's line items, so always send the full list with the final quantity of each item. Omitting `line_items`, or sending an empty array, empties the cart.

For drop shipping, use a temporary shipping address when the delivery address shouldn't be stored against the customer's account.

### Validation

Each cart update returns the latest cart state, including any validation errors generated by your business rules in SparkLayer, such as:

- Minimum or maximum order quantity restrictions
- Product availability constraints
- Customer-specific purchasing restrictions

The response also has a result for each line item, so you can see how each requested item was processed and whether it was adjusted or has a validation error.

The [Update a cart](https://docs.sparklayer.io/developers/api/ordering/update-cart.md) and [Calculate a cart](https://docs.sparklayer.io/developers/api/ordering/calculate-cart.md) operations don't fail because of validation errors: the errors are included in the response for your application to handle. Calculating does return a `422` if the cart is empty or the shipping rate you chose isn't available — see [Cart errors](https://docs.sparklayer.io/developers/errors.md#cart-errors).

The [Complete a cart](https://docs.sparklayer.io/developers/api/ordering/complete-cart.md) operation behaves differently. If validation errors exist, it returns a `422` and the cart isn't completed. To allow specific validation errors, list them in the `ignore_validation_errors` property.

## 3. Calculate the cart

[Calculate the cart](https://docs.sparklayer.io/developers/api/ordering/calculate-cart.md) before completing it. SparkLayer:

- Calculates the order totals and tax with the connected platform
- Applies pricing
- Returns the available shipping methods and their costs
- Returns the allowed payment methods
- Validates the current cart state

To choose a shipping method, pass its `shipping_rate_handle`. If you leave it out, SparkLayer uses the first available shipping rate. Calculate again after changing the shipping rate or the cart, so the totals you show are up to date. 

## 4. Complete the cart

[Complete the cart](https://docs.sparklayer.io/developers/api/ordering/complete-cart.md) once it's valid and you've chosen how to ship and pay. Send:

- `shipping_rate_handle`: a shipping rate returned when you calculated the cart
- `payment_method`: `paymentByInvoice` or `paymentOnAccount`
- `ignore_validation_errors`: the validation errors to allow (an empty list allows none, `"*"` allows all)

Completing a cart turns it into a SparkLayer order and submits it to the connected eCommerce platform.

The response includes the new `purchase_id`. The cart is deleted once it's completed, so later requests with its ID return `404`.

## Endpoints

_Every operation is listed under "API operations" at the top of this file._

## Next steps

- [Authentication](https://docs.sparklayer.io/developers/authentication.md): get an access token for your requests.
- [Errors](https://docs.sparklayer.io/developers/errors.md#cart-errors): the cart error codes and what they mean.
- [Purchasing API](https://docs.sparklayer.io/developers/api/purchasing.md): the orders and quotes customers see in My Account.


---

# Pricing API

URL: https://docs.sparklayer.io/developers/api/pricing

The Pricing API syncs price lists and SKU pricing from your ERP or PIM into SparkLayer, including customer-specific pricing. Covers the flow and endpoints.

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:

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.
2. Price lists are imported into SparkLayer through the SparkLayer API, each with a name, ID and currency code.
3. Price lists are assigned to individual product SKUs. It's common for a SKU to have several price lists.
4. Customers are also assigned a price list in SparkLayer, matching your backend system (e.g. Customer A sees Price list 1, Customer B sees Price list 2).
5. When the customer signs in and visits a product page, the SparkLayer Frontend recognises them (and their price list) and shows their price.

## 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](https://docs.sparklayer.io/developers/api/pricing/get-price-lists-v2.md). 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](https://docs.sparklayer.io/developers/api/pricing/create-a-price-list.md). 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](https://docs.sparklayer.io/developers/api/pricing/update-pricing-by-price-list.md).

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](https://docs.sparklayer.io/help/platforms/shopify/metafields.md).

## 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**.
- A **price list** links to **prices**.
- Each **price** is linked to a product **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** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/pricing/editor)), or **SparkLayer Wholesale > Pricing > Price editor** in the Shopify app.

## Endpoints

_Every operation is listed under "API operations" at the top of this file._

## Next steps

- [API quickstart](https://docs.sparklayer.io/developers/quickstart.md): get a token and list your price lists.
- [Managing pricing](https://docs.sparklayer.io/help/pricing/managing-pricing.md): how merchants work with price lists in the Dashboard.
- [Stock API](https://docs.sparklayer.io/developers/api/stock.md): sync stock levels alongside your prices.


---

# Purchasing API

URL: https://docs.sparklayer.io/developers/api/purchasing

Store orders, quotes and carts shown in My Account with the Purchasing API, using purchase identifiers, packages and purchase transactions. Lists all endpoints.

The Purchasing API stores your customers' purchases: carts, quotes, purchases awaiting approval or confirmation, and placed orders. Use it to keep the orders shown in My Account up to date.

> **Purchases aren't sent to your eCommerce platform**
>
> Purchases you create with this API show in the My Account area for your B2B customers, but SparkLayer doesn't push them to your eCommerce platform (such as Shopify). To have an order on your platform too, create it with the platform's own API, such as the [Shopify order API](https://shopify.dev/docs/api/admin-rest/latest/resources/order).

For orders created on your platform to sync to SparkLayer, they need a few properties, which depend on your platform. On Shopify, each order needs:

- The `b2b` tag
- The `sparklayer.order_import` metafield, set to `true`

See [Import order history into SparkLayer](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#import-order-history-into-sparklayer) for the Shopify steps.

## Creating and updating purchases

Create and update purchases with [Create or update a purchase](https://docs.sparklayer.io/developers/api/purchasing/create-update-purchase.md) (`PUT /api/v1/purchases/{lookupBy}/{identifier}`). If no purchase matches `lookupBy` and `identifier`, a new one is created.

- **Send the full purchase every time.** The request replaces the purchase's previous data, so include every field, not just the ones that changed. This prevents stale data and keeps order integrations simple.
- **Leave out calculated fields.** The API calculates them, so don't set them in the request body.
- **Expect a `400` for missing or invalid values.** The error identifies the value to fix.

### Purchase identifiers

The `purchase_identifiers` object holds the purchase's IDs in each system. Use one of them as `lookupBy`:

| Identifier | Description |
| --- | --- |
| `sparklayer` | SparkLayer's ID for the purchase (a UUID). For an order placed through SparkLayer, this is the ID of the SparkLayer cart, which SparkLayer passes to your eCommerce platform when the customer completes checkout. Send it so the order moves from `awaiting_merchant` to `order` and replaces the cart. For other orders, leave it blank. |
| `platform` | The purchase's ID on your eCommerce platform. |
| `internal` | Your ID for the purchase, such as the order number in your ERP or order management system (OMS). |
| `visible` | The ID shown to the customer in their recent orders. |

### Purchase types

Most integrations send purchases of type `order`.

| Purchase type | Description |
| --- | --- |
| `quote` | A quote, with a quote status. |
| `awaiting_approval` | A purchase waiting for another person at the customer's company to approve it, typically with [company users](https://docs.sparklayer.io/help/customers/company-users.md). |
| `awaiting_merchant` | An order completed in SparkLayer but not yet confirmed, because it's pending on the eCommerce platform or the sync hasn't finished. |
| `order` | A finalised order, saved on the eCommerce platform or in your order source of truth, such as an ERP or OMS. |

### Packages

A purchase is mostly made up of packages, which hold the line items, shipping methods, addresses and IDs.

1. When you first create an order, put its line items in a `processing` package.
2. As the order progresses, move items to the relevant packages, such as `shipment`, `return` or `cancelled`. You can have more than one of each, for example for partial shipments.

The order status customers see is calculated from the package dates, such as when each package was created and shipped.

## Purchase transactions

Record payments, refunds and other transactions against a purchase with [Create or update a purchase transaction](https://docs.sparklayer.io/developers/api/purchasing/create-or-update-a-purchase-transaction.md). SparkLayer uses the transactions to calculate the purchase's payment status.

If you record transactions with this API, don't also send them to your eCommerce platform: the same transaction could be recorded twice.

- **Identify the purchase** in the request URL, with `lookupBy` and `identifier`. A purchase can have many transactions, but each needs a unique `platform_id`: the ID the third-party system (such as your payment provider) uses for the transaction. `purchase_spark_id` in the response is read-only, so don't send it.
- **Set the amount** in `total`: positive for a payment, negative for a refund. A `currency_code` is also required. 
- **Choose whether it counts** with `apply_to_balance`.

| `apply_to_balance` | What happens |
| --- | --- |
| `false` | The transaction is stored for information only, and isn't used to calculate the payment status. The [list endpoint](https://docs.sparklayer.io/developers/api/purchasing/get-purchase-transactions.md) returns it, but nothing else happens. Use this for pending or failed transactions, which can help with debugging. |
| `true` | The transaction counts towards the purchase's payment status. SparkLayer also adds an entry to the purchase history, which the customer sees, and adjusts the outstanding balance of the purchase's customer by the `total`. |

Changing a transaction from `true` to `false` deletes the history entry it created, and reverses the change to the customer's balance and payment status.

Use `full_transaction` to store the full transaction, as a JSON string, as the third-party system holds it. SparkLayer stores it as given, without redacting anything, so remove or obscure sensitive data, such as full card numbers, before you send it.

## Endpoints

_Every operation is listed under "API operations" at the top of this file._

## Next steps

- [Authentication](https://docs.sparklayer.io/developers/authentication.md): get an access token for your requests.
- [Ordering API](https://docs.sparklayer.io/developers/api/ordering.md): place orders on behalf of customers.
- [Files API](https://docs.sparklayer.io/developers/api/files.md): download the files customers attach to orders.


---

# Stock API

URL: https://docs.sparklayer.io/developers/api/stock

The Stock API reads, batch updates and deletes stock levels by SKU and manages stock locations for your SparkLayer site. Lists every endpoint and its responses.

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

_Every operation is listed under "API operations" at the top of this file._

## Next steps

- [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md): how stock levels show to B2B customers.
- [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md): sync prices alongside stock.


---

# Files API

URL: https://docs.sparklayer.io/developers/api/files

Upload, update and download files with the SparkLayer Files API using expiring URLs, and retrieve order file attachments from their GIDs. Lists all endpoints.

The Files API stores and retrieves files in SparkLayer. SparkLayer uses it for order file attachments, and you can use it to upload files or download the files attached to your orders.

## How it works

> **URLs expire**
>
> The upload and download URLs returned by the API expire after 15 minutes.

### Uploading a file

Uploading takes two requests:

1. [Create a file](https://docs.sparklayer.io/developers/api/files/create-a-new-file.md) (`POST /api/v1/files`) with the file's path, including its name, in `file_path`. Like every API request, it needs your access token and Site ID:

   ```bash title="Create a file"
   curl -X POST https://app.sparklayer.io/api/v1/files \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Site-Id: <SITE_ID>" \
     -H "Content-Type: application/json" \
     -d '{ "file_path": "folder/file.pdf" }'
   ```

   The response includes the file's `id`, a signed upload `url` and a list of `required_headers`.

2. Upload the file's contents with an HTTP `PUT` to that `url`, sending **every** header in `required_headers` (for example `Content-Type`). If any are missing, the upload fails. The signed URL grants access by itself, so this request doesn't need your `Authorization` or `Site-Id` headers:

   ```bash title="Upload the contents"
   curl --upload-file 'file.pdf' \
     -H "Content-Type: application/pdf" \
     '<UPLOAD_URL>'
   ```

Files can be up to 20 MB. Use the file's `id` with the other endpoints. To replace a file's contents, [update the file](https://docs.sparklayer.io/developers/api/files/update-a-file.md) (`PATCH /api/v1/files/{id}`) to get a new upload URL, then upload again. 

### Downloading a file

To download a file, [get the file](https://docs.sparklayer.io/developers/api/files/get-a-file.md) (`GET /api/v1/files/{id}`). Once the upload has completed, this returns a download URL, some file metadata and a list of `required_headers`. Download the file from the URL, sending those headers.

### Failed uploads

If the file's contents don't match its file extension, the file is deleted, and `GET /api/v1/files/{id}` returns `410 Gone`.

### Downloading order file attachments

To download the files attached to a B2B order, use `GET /api/v1/files/{id}`. SparkLayer stores the IDs of attached files in the order's note attributes, under the name set in `checkoutCustomElements` in your theme (`file-upload` by default). They're stored as a JSON array:

```json title="Order note attribute"
[
  "gid://sparklayer/File/fdc70d92-fcdf-4719-af2b-9d319a5035d2",
  "gid://sparklayer/File/a7a3ee08-c6d0-49ee-89b4-bcdaf780d553",
  "gid://sparklayer/File/15be5381-0b50-459f-9643-af236b9f29f7"
]
```

Remove the `gid://sparklayer/File/` prefix from each one to get the file ID, for example `fdc70d92-fcdf-4719-af2b-9d319a5035d2`.

## Endpoints

_Every operation is listed under "API operations" at the top of this file._

## Next steps

- [Authentication](https://docs.sparklayer.io/developers/authentication.md): get the access token the API requests need.
- [Custom attributes and files](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#custom-attributes-and-files): let customers attach files to cart items.
- [Purchasing API](https://docs.sparklayer.io/developers/api/purchasing.md): look up the orders the files belong to.


---

# Sync Logging API

URL: https://docs.sparklayer.io/developers/api/sync-log

The Sync Logging API records full and partial data syncs, sync errors and status between your systems and SparkLayer. Lists every endpoint and its parameters.

The Sync Logging API records the progress of data syncs between an integration and SparkLayer — when full and partial syncs ran, and which records failed to sync and why. Logs are kept per integration and data type.

## How it works

1. **Record each full sync** with **Record a full sync** (`PUT`). This sets the `started_full_sync` and `last_full_sync` timestamps and replaces the logged errors with the ones you send. A timestamp you leave out is cleared.
   - For a quick sync, send one `PUT` when it finishes, with both timestamps and all the errors.
   - For a long or asynchronous sync, send a `PUT` with `started_full_sync` when it starts, record errors with `PATCH` requests as items sync, and send a final `PATCH` with `last_full_sync` once every item has synced.
2. **After each partial (incremental) sync**, use **Record a partial sync** (`PATCH`) to update `last_partial_sync`, clear errors for records that now sync successfully (listed in `successfully_synced`), and add new errors.
3. **Read the status and errors** with **Get a sync status** and **List sync errors**.

Record a full sync before any partial syncs: until one exists, the status endpoints return `404` and partial sync timestamps aren't saved. Each error's `external_id` must be unique within a request.

For how an Ignite integration logs its syncs, see [Ignite data sync](https://docs.sparklayer.io/ignite/data-sync.md#logging-sync-issues).

## Endpoints

_Every operation is listed under "API operations" at the top of this file._

## Next steps

- [Authentication](https://docs.sparklayer.io/developers/authentication.md): get an access token for your requests.
- [Ignite data sync](https://docs.sparklayer.io/ignite/data-sync.md): what to sync from a custom platform, and when.


---

# Frontend integration guide

URL: https://docs.sparklayer.io/developers/frontend

Install the SparkLayer Frontend: add the Core Script or Shopify app embed, add product page widgets, hide retail elements with data-spark and style with CSS.

The SparkLayer Frontend is what your B2B customers see on your website: their prices, the cart, quick order and their account. Adding it takes a few small code changes to your theme. Once they're in place, B2B customers can log in and start placing orders.

It takes three steps:

**Step 1.** **Add the Core Script**

One script in your theme that loads SparkLayer on every page.

**Step 2.** **Add the product page widgets**

They show each customer their own prices on product pages, and let them add products to an order.

**Step 3.** **Match your design**

CSS variables set the colours, typefaces and spacing, so SparkLayer looks like the rest of your site.

After that, you can tailor the B2B experience further: [Storefront](https://docs.sparklayer.io/help/storefront.md) has the settings, and [Integrations](https://docs.sparklayer.io/help/integrations.md) has advice for each platform.

> **Personalised instructions**
>
> In the SparkLayer Dashboard, **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app gives you personalised instructions for adding the code snippets to your website.

## The SparkLayer Core Script

The Core Script is a JavaScript snippet in your website's theme. It loads the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) your B2B customers use to place orders, manage their account and more.

### Installing the script

**Shopify:**

On Shopify, the **SparkLayer app embed** loads the Core Script for you, so there's no need to edit `theme.liquid` or other theme files.

To enable it:

1. Go to the [Theme setup](https://admin.shopify.com/apps/sparklayer/theme-setup) page in the SparkLayer Shopify app
2. Select your theme from the **Theme** dropdown
3. Click **Enable app embed** - this opens your Shopify theme editor in a new tab
4. In the theme editor, click **Save** in the top right to activate the app embed

The Core Script now loads on your storefront. You can verify it's working by checking the **App Blocks** table on the same page, where the **App Embed** row should show as Enabled.

![Installing the script (Shopify) – Frontend Integration Guide](https://docs.sparklayer.io/images/developers/frontend/frontend-0cfafd.webp)

If you'd prefer not to install SparkLayer yourself, our team can do this for you free of charge. On the Theme setup page, click **Install SparkLayer for me** to request a free install.

**Other platforms:**

Add the SparkLayer Core Script to the `<head>...</head>` of your website's theme so it loads on every page. On BigCommerce, this is typically in `/templates/layout/base.html`.

![Installing the script (Other platforms) – Frontend Integration Guide](https://docs.sparklayer.io/images/shared/frontend-61c96b.webp)

Your customised Core Script is in the SparkLayer Dashboard at **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app.

```html title="Core Script"
<script async src="https://sparkcdn.io/sparkjs/yourstorehere/live"></script>
```

A new installation uses the latest version of the Core Script. You can change the version later (see [Upgrading to the latest version](#upgrading-to-the-latest-version)), and [What's new](https://docs.sparklayer.io/help/whats-new.md) lists the changes in each release.

### Technical details

The Core Script gives SparkLayer the information that controls how it works on your website.

```html title="Core Script with options"
<!-- Copy your own from the SparkLayer Dashboard: Storefront > Widgets -->

<script>
  window.sparkOptions = {
    siteId: "examplestore", // your unique site id
    platform: "shopify", // your platform
    rootUrl: {{ routes.root_url | json }},
    language: {{ request.locale.iso_code | json }},
    accountRedirect: {
      urlRegex: /\/account/g,
      goTo: "/index", // page to redirect logged in users to
    },
    display: {
      stock: {
        show: false, // set to true to show stock level display
        max: 50, // highest stock level to show
        last: 5, // last remaining stock threshold
        low: 15, // low stock threshold
      },
    },
    auth: {
      user: {{ customer.email | json }},
      token: {{ customer.metafields.sparklayer.authentication | json }},
    },
  };
</script>
<script async src="https://sparkcdn.io/sparkjs/yourstorehere/live"></script>
```

This information includes:

| Item | Details |
| --- | --- |
| `siteId` | The website's unique identifier (see [your account and team](https://docs.sparklayer.io/help/dashboard/account.md)) |
| `platform` | The eCommerce platform of the website |
| `language` | The language to be used |
| `accountRedirect` | Where to send logged-in customers who visit a matching URL (`urlRegex`), and the page to send them to (`goTo`) |
| `display` | Which display configurations to enable (see [Storefront](https://docs.sparklayer.io/help/storefront.md)). Since Core Script 2.0, stock display is set per customer group in the Dashboard instead (see [stock display](https://docs.sparklayer.io/help/storefront/stock-display.md)) |
| `auth` | The authentication details of the logged in customer |

### Modifying the core script

The Core Script's options turn specific features on or off and customise how they work.

**Shopify:**

On Shopify, the app embed loads the Core Script for you. To add customisations or configurations, add a small `<script>` block to your theme that defines them.

Add the following to your theme's `theme.liquid` file, just before the closing `</head>` tag:

```html title="theme.liquid"
<script>
  window.sparkOptions = {
    ...window.sparkOptions,
    // Add your customisations here
  };
</script>
```

The `...window.sparkOptions` line keeps any options your theme or another snippet has already set; without it, the new object replaces them.

For example, to set the language and send logged-in customers who visit an account page to your collections page:

```html title="theme.liquid"
<script>
  window.sparkOptions = {
    ...window.sparkOptions,
    language: 'en',
    accountRedirect: {
      urlRegex: /\/account/g,
      goTo: '/collections/all',
    },
  };
</script>
```

The `window.sparkOptions` block must come **before** the SparkLayer app embed loads, so place it in the `<head>` of your theme, not the `<body>` or footer.

**Other platforms:**

On other platforms, `window.sparkOptions` is part of the Core Script you added to your theme's `<head>`. Change the options in that block: see [Technical details](#technical-details) for an example and what each option does, and the [Core Script options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md) for every option.

For every option, see the [Core Script options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md). For the settings merchants manage in the Dashboard, see [Storefront](https://docs.sparklayer.io/help/storefront.md).

### Upgrading to the latest version

To upgrade to the latest version of the Core Script, go to **Storefront > Widgets** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/frontend/core)), or **SparkLayer Wholesale > Storefront > Widgets** in the Shopify app in the SparkLayer Dashboard.

**Step 1.** In the **Upgrade Core Script** section, select the latest numeric version, then click **Save**.

**Step 2.** Update your website so it loads the matching Core Script. If you're not already on version 2, your Core Script looks something like this:

```html title="Version 1 Core Script"
<script async src="https://cdn.sparklayer.io/spark.1.36.x.js"></script>
```

Replace it with the version 2 format:

```html title="Version 2 Core Script"
<script async src="https://sparkcdn.io/sparkjs/<site-id>/<env>"></script>
```

| Item | Details |
| --- | --- |
| `<site-id>` | Your unique Site ID, shown in the SparkLayer Dashboard at **Account** ([open in the SparkLayer Dashboard](https://app.sparklayer.io/settings/account)) |
| `<env>` | The SparkLayer environment: `live`, or `test` if you're using [test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md) |

For example, for a store with Site ID `b2bstore` on the `live` environment:

```html title="Version 2 Core Script"
<script async src="https://sparkcdn.io/sparkjs/b2bstore/live"></script>
```

## Product page widgets

The product page widgets are the parts of SparkLayer B2B customers see on your product and collection pages when they log in. There are three:

**Step 1.** **[Product detail](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md)**

Shown on your product detail pages, it lets customers quickly add products to an order in a table view.

![Product page widgets – Frontend Integration Guide](https://docs.sparklayer.io/images/developers/frontend/frontend-f499d1.webp)

**Step 2.** **[Product card](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md)**

Shown wherever a product card appears, such as a collection page or a product upsell area.

![Product page widgets – Frontend Integration Guide](https://docs.sparklayer.io/images/developers/frontend/frontend-535a99.webp)

**Step 3.** **[Product price](https://docs.sparklayer.io/help/storefront/interfaces/product-price.md)**

Shows a product's B2B price anywhere on your website, such as a product detail page or collection page.

![Product page widgets – Frontend Integration Guide](https://docs.sparklayer.io/images/developers/frontend/frontend-b67dc7.webp)

Adding them takes two steps:

**Step 1.** **Hide the retail elements**

If you're installing SparkLayer on your existing retail website, **hide** the elements B2B customers shouldn't see, such as your retail pricing, add to cart button, variant options and quantity selector. SparkLayer has an attribute you can add to any HTML element to do this (see [Hiding elements](#hiding-elements)).

**Step 2.** **Add the widgets**

Add the SparkLayer code snippets to your product pages, such as the product detail page and collection page. When a B2B customer logs in, the interfaces show automatically, so they can see prices, add items to an order, view their account and check out. See [Storefront widgets](https://docs.sparklayer.io/help/storefront/interfaces.md) for each interface and how to customise it.

### Hiding elements

SparkLayer can hide any element on your website from B2B customers with a `data-spark` attribute.

Elements you would typically hide include:

- Price information
- Product variant information
- Quantity selection
- Buy button

![Hiding elements – Frontend Integration Guide](https://docs.sparklayer.io/images/developers/frontend/frontend-25ee14.webp)

You need access to your website's source code to find the files that contain the elements you want to hide, such as:

- A product detail page
- A product collection page
- Specific "components" that are used in multiple locations on your website

In those files, add `data-spark="b2c-only"` to each element you want to hide. SparkLayer then applies `display: none` to the element when a logged-in B2B customer views the page.

This step changes your website's code, so you may want a developer to help. For platform-specific guidance, see [Integrations](https://docs.sparklayer.io/help/integrations.md).

```html title="Hiding elements from B2B customers"
<div data-spark="b2c-only">
  <!-- Anything inside here will be hidden for B2B customers -->
</div>

<p class="price" data-spark="b2c-only">
  <!-- In this example, the price would be hidden -->
  {{ product.price }}
</p>

<!-- Repeat this process for any HTML element you want hidden -->
```

### Displaying the SparkLayer interfaces

Next, add the SparkLayer [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) to your pages. Each interface's page explains how to add its code snippet.

| Interface | Details |
| --- | --- |
| [Product detail](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) | Shown on your product detail pages; lets customers quickly add products to an order. |
| [Product card](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) | Shown wherever a product card appears, such as a collection page. |
| [Product price](https://docs.sparklayer.io/help/storefront/interfaces/product-price.md) | Shows a product's B2B price anywhere on your website, instead of or alongside the product card. |

## Design customisations (CSS)

SparkLayer's interface is neutral by default, and you can change nearly every aspect of its look and feel with CSS variables, including:

- Colours
- Typography (e.g. typefaces and font sizing)
- Spacing (e.g. padding and margin)
- Button styling
- Form styling

Add the CSS to your existing stylesheets, or to your website's `<head>...</head>` as you did with the Core Script.

![Design customisations (CSS) – Frontend Integration Guide](https://docs.sparklayer.io/images/shared/frontend-e2b840.webp)

### What can be styled

To find the styles you want to change, use your browser's **Inspect element** tool. SparkLayer's styles use CSS variables prefixed with `--spark-`, and you can override each one.

In the inspector, you'll see something like the example below. To change a style, such as a button colour, set the matching variable in your website's CSS. See [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md) for details.

```css title="SparkLayer button styles"

.btn, .btn-large, .btn-small {
    color: var(--spark-button-raised-color,var(--spark-lightest-color,#fff));
    background-color: var(--spark-button-raised-background,var(--spark-secondary-color,#125ef8));
    border: var(--spark-button-border,none);
    border-radius: var(--spark-button-radius,var(--spark-border-radius-button,4px));
    padding: var(--spark-button-padding,.875em 1.75em);
    text-transform: var(--spark-button-text-transform,none);
    letter-spacing: var(--spark-button-text-letter-spacing,0);
    font-weight: var(--spark-button-font-weight,400);
    font-family: var(--spark-button-font-family,Poppins,sans-serif);
}
```

## Frontend integration checklist

Before you launch, check you've covered everything:

- **Core Script added.** You've added the SparkLayer Core Script to your website's `<head>`. On Shopify, you've enabled the SparkLayer app embed.
- **Product detail widget added.** You've added the SparkLayer product detail widget to your product detail pages, and hidden content B2B customers shouldn't see, such as your regular direct-to-consumer (DTC) pricing, add to cart buttons, "sticky" content that references pricing, and non-B2B content.
- **Product card widget added.** You've added the SparkLayer product card widget to your product cards (typically on collection and category pages), and hidden DTC pricing, add to cart buttons, "quick buy" buttons and non-B2B content.
- **Every product card checked.** You've checked all areas of your website that show product cards, such as the homepage and product recommendations.
- **CSS and design.** You've added the SparkLayer CSS to your website (in the header or a CSS file) and styled it to match your branding.
- **Cart and cart drawer.** Clicking the cart icon in your website header opens the My Cart interface. If it doesn't, make sure the cart link points to `/cart` and doesn't trigger your theme's JavaScript for B2B customers.
- **General site audit.** You've checked features such as site search and wish lists, so DTC prices are hidden (in CSS or in the code).

## Next steps

- [Storefront widgets](https://docs.sparklayer.io/help/storefront/interfaces.md): add and customise each interface.
- [Core Script options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md): every `sparkOptions` setting.
- [Technical information](https://docs.sparklayer.io/developers/frontend/technical-information.md): browser support and analytics event tracking.
- [JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk.md): build custom or headless interfaces.


---

# Technical information

URL: https://docs.sparklayer.io/developers/frontend/technical-information

How the SparkLayer Frontend loads asynchronously, supported browsers and devices, and how to track B2B events in GA4 or Google Tag Manager via sparkOptions.

SparkLayer is designed to be as lightweight as possible and uses modern JavaScript technology to power the frontend.

## How SparkLayer is loaded

SparkLayer is fully hosted, so there's no code for you to host or maintain.

For performance, the SparkLayer Frontend **only** loads when a customer logs in to your website. The interfaces load asynchronously, so even though SparkLayer is a hosted third-party solution, the impact on page load times is negligible.

## Browser support

SparkLayer supports the latest two versions of these browsers:

- Google Chrome
- Mozilla Firefox
- Apple Safari
- Microsoft Edge
- Apple Safari for iOS
- Google Chrome for Android and iOS

SparkLayer may not work fully with beta or pre-release versions of these browsers.

## Mobile support

The [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md) work on desktop, tablet and mobile, so customers can browse your website on any device.

## Building custom interfaces

To build more custom layouts on top of the SparkLayer Frontend, see the [JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk.md).

## Event tracking for analytics (Google Analytics, GA4)

SparkLayer can send B2B events, such as add to cart, begin checkout and purchase, to Google Analytics (GA4), Google Tag Manager (GTM) or your own analytics code. You set it up with the `analytics` option in `sparkOptions`, so you'll need a developer to add it to your [Core Script](https://docs.sparklayer.io/developers/frontend.md#modifying-the-core-script).

### Enabling Google Analytics or GTM

Add an `analytics` object with a list of `providers`. Each provider has a `handler` (which analytics tool to send to) and the `events` to send. This example sends every event to GA4, GTM and a custom function:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  analytics: {
    providers: [
      {
        handler: 'ga', // Google Analytics (GA4)
        events: {
          addToCart: true,
          cartUpdate: true,
          shoppingListSave: true,
          shoppingListLoad: true,
          shoppingListDelete: true,
          csvUpload: true,
          quickAdd: true,
          finalStageCheckout: true,
          shippingUpdate: true,
          beginCheckout: true,
          purchase: true,
          viewCart: true,
        },
      },
      {
        handler: 'gtm', // Google Tag Manager
        events: {
          addToCart: true,
          cartUpdate: true,
          shoppingListSave: true,
          shoppingListLoad: true,
          shoppingListDelete: true,
          csvUpload: true,
          quickAdd: true,
          finalStageCheckout: true,
          shippingUpdate: true,
          beginCheckout: true,
          purchase: true,
          viewCart: true,
        },
      },
      {
        handler: function (eventName, eventParam) {
          // Your own analytics code
        },
        events: {
          addToCart: true,
          purchase: true,
        },
      },
    ],
  },
};
```

The `...window.sparkOptions` line keeps the options you've already set; without it, this object replaces them.

### Provider options

| Provider type | Description |
| --- | --- |
| `'ga'` | Integrates with Google Analytics (GA4). This works best with [Shopify's GA4 integration](https://help.shopify.com/en/manual/reports-and-analytics/google-analytics/google-analytics-setup). |
| `'gtm'` | Integrates with Google Tag Manager. |
| function | A custom analytics handler, for other analytics platforms or your own tracking logic. See [Custom analytics provider](#custom-analytics-provider). |

### Available events

| Event name | Description |
| --- | --- |
| `addToCart` | Triggered when a product is added to the cart. |
| `cartUpdate` | Fired when the cart is updated (for example, quantity changes or items removed). |
| `shoppingListSave` | Occurs when a shopping list is saved. |
| `shoppingListLoad` | Occurs when a shopping list is loaded. |
| `shoppingListDelete` | Occurs when a shopping list is deleted. |
| `csvUpload` | Triggered when a CSV file is uploaded. |
| `quickAdd` | Fired during quick add actions. |
| `finalStageCheckout` | Occurs at the final stage of the checkout process. |
| `shippingUpdate` | Fired when shipping details are updated during checkout. |
| `beginCheckout` | Triggered when the checkout process begins. |
| `purchase` | Occurs when a purchase is completed. |
| `viewCart` | Fired when the cart is viewed. |

### Custom analytics provider

To send events to an analytics service SparkLayer doesn't support natively, set `handler` to a function. It receives the event name and its parameters, so you can add any tracking logic:

```javascript title="Custom analytics provider"
{
  handler: function (eventName, eventParam) {
    // Example: send the event to your own analytics endpoint
    fetch('https://your-analytics-endpoint.com/track', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        event: eventName,
        parameters: eventParam,
      }),
    });
  },
  events: {
    addToCart: true,
    cartUpdate: true,
    // ... other events ...
  },
}
```

## Next steps

- [Frontend integration guide](https://docs.sparklayer.io/developers/frontend.md): install the Core Script and product page widgets.
- [Core Script options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md): every `sparkOptions` setting.
- [Set up the JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md): customise the frontend with code.


---

# JavaScript SDK

URL: https://docs.sparklayer.io/developers/javascript-sdk

What the SparkLayer JavaScript SDK is, what you can build with it, how it loads with the Core Script, and a first example that fetches a customer's price.

The JavaScript SDK lets your own code work with SparkLayer on your storefront. Your theme can read the same data SparkLayer's own screens use, such as a customer's prices and cart, take the same actions, such as adding to the cart, and run code at key moments, such as just before checkout.

In code, the SDK is the `window.spark` object, which SparkLayer's [Core Script](https://docs.sparklayer.io/help/glossary.md#core-script) adds to every page.

## What you can build

- **Custom pricing displays**: show a customer's price, RRP or price breaks anywhere in your theme. See [Products and pricing](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md).
- **Your own add to cart**: add products, quantities and custom attributes (including files) to the cart. See [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md).
- **Checkout rules**: block checkout with your own validation, such as a product quota checked against your API. See [Checkout](https://docs.sparklayer.io/developers/javascript-sdk/checkout.md).
- **Customer and sales agent tools**: check who's logged in, switch the customer a sales agent orders for, or query their data. See [Customers and accounts](https://docs.sparklayer.io/developers/javascript-sdk/customers-and-accounts.md).
- **Theme integration**: swap variant images, open the cart drawer or send events to your analytics. See [Events and analytics](https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics.md).
- **Headless storefronts**: load and initialise SparkLayer yourself in a custom frontend. See [Headless and React](https://docs.sparklayer.io/developers/javascript-sdk/headless.md).

### Choose the most stable way to customise

You can build around SparkLayer's own components, and change them too. Prefer the ways that keep working when SparkLayer updates:

1. An **option** or **hook** in the SDK.
2. A [CSS variable](https://docs.sparklayer.io/help/storefront/customising-design.md) for the look, or a [custom slot](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md) to add your own content.
3. Only if neither does the job, change a component's HTML. Keep the change small, and check it after each SparkLayer update.

Planning something bigger? [Talk to our team](https://docs.sparklayer.io/help/support.md) first.

## Build it with AI

Most SDK customisations are a few dozen lines of code, which suits an AI assistant well. Describe what you want, and the prompt below gives your assistant the SDK reference and the rules to follow. Review the code it writes, and test it on an unpublished theme or a test store before it goes live.

For work with the SparkLayer APIs, see [Build with AI](https://docs.sparklayer.io/developers/build-with-ai.md).

## How the SDK loads

The SDK comes with the Core Script, so there's nothing extra to install. On Shopify, the SparkLayer app embed loads it. On other platforms, you add the Core Script to your theme's `<head>` from the SparkLayer Dashboard.

Two rules apply to all SDK code:

- **Set your options first.** You configure the SDK with `window.sparkOptions`, which must be set **before** the Core Script loads.
- **Wait until SparkLayer is ready.** `window.spark` only works once SparkLayer has started, so run your code from the `onReady` hook.

[Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md) covers both in detail.

## Try it: show a customer's price

Add this to your theme's `<head>`, before the Core Script. When SparkLayer is ready, it checks whether a customer is logged in and, if they are, writes their price for one product to the browser console:

```html title="theme.liquid or your theme's <head>"
<script>
  window.sparkOptions = {
    ...window.sparkOptions,
    onReady: async (spark) => {
      if (!(await spark.isLoggedIn())) {
        return;
      }

      // Use a parent product ID and variant SKU from your store
      const pricing = await spark.getPricingForVariant('6660191387839', 'MUG-MOM');
      console.log(pricing.price, pricing.currencyCode, pricing.priceBreaks);
    },
  };
</script>
```

Open a product page as a logged-in B2B customer and check the browser console. The `...window.sparkOptions` line keeps the options already set by the Core Script or other snippets: see [Add your own options and hooks](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#add-your-own-options-and-hooks).

If one of your hooks throws an error, SparkLayer shows a system error with a code such as `OPTIONS:HOOK:OR`. See [Hook error codes](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#hook-error-codes).

## Next steps

- [Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md): Load the Core Script, add your own options and hooks, and wait for SparkLayer to be ready.
- [Products and pricing](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md): Show trade prices, live quantity pricing and the right image for each variant.
- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Add and remove items, set cart fields, attach attributes and files, and open the drawer.
- [Checkout](https://docs.sparklayer.io/developers/javascript-sdk/checkout.md): Block checkout until your own rules are met.
- [Customers and accounts](https://docs.sparklayer.io/developers/javascript-sdk/customers-and-accounts.md): Check the login, work as a sales agent, switch company sections and run GraphQL queries.
- [Events and analytics](https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics.md): Hooks, DOM events and sending B2B events to Google Analytics or your own tools.
- [Headless and React](https://docs.sparklayer.io/developers/javascript-sdk/headless.md): Load and initialise SparkLayer yourself, with Next.js and React examples.
- [SDK reference](https://docs.sparklayer.io/developers/javascript-sdk/reference.md): Every sparkOptions setting, hook, window\.spark method, type, DOM event and web component.


---

# Set up the SDK

URL: https://docs.sparklayer.io/developers/javascript-sdk/setup

Load the SparkLayer Core Script, add your own sparkOptions and hooks without overwriting others, and wait for SparkLayer to be ready before calling it.

Every SDK customisation starts here: how the SDK loads with the Core Script, how to add your own options and hooks without overwriting anyone else's, and how to wait until SparkLayer is ready. It uses `window.sparkOptions`, the `onReady` hook and, on headless storefronts, `window.initSpark()`.

## How the SDK loads

The SDK comes with the SparkLayer Core Script. On Shopify, the SparkLayer app embed loads it. On other platforms, the Core Script you copy from the SparkLayer Dashboard goes in your theme's `<head>`:

```html title="Core Script"
<script async src="https://sparkcdn.io/sparkjs/<SITE_ID>/live"></script>
```

Replace `<SITE_ID>` with your Site ID, and use `test` instead of `live` in [test mode](https://docs.sparklayer.io/help/dashboard/test-mode.md). The version this URL serves is set in the Dashboard: see [Upgrading to the latest version](https://docs.sparklayer.io/developers/frontend.md#upgrading-to-the-latest-version). For the rest of the storefront setup, see the [frontend integration guide](https://docs.sparklayer.io/developers/frontend.md#the-sparklayer-core-script).

Older themes may load a version 1 file such as `https://cdn.sparklayer.io/spark.1.0.21.js`. These URLs are legacy: replace them with the loader above. Don't use `spark.latest.js` either: it's a legacy bundle that lacks most of the SDK.

When the Core Script runs, it reads `window.sparkOptions`, starts SparkLayer and sets `window.spark`. Your options and hooks must therefore be in place **before** the Core Script loads.

## Add your own options and hooks

Set your options in a `<script>` in the `<head>`, before the Core Script, and always extend the existing object rather than replacing it:

```html title="theme.liquid or your theme's <head>"
<script>
  window.sparkOptions = {
    ...window.sparkOptions,
    language: 'en',
    onCartUpdate: async (cart, results) => {
      // Your code here
    },
  };
</script>
```

`window.sparkOptions = { … }` on its own replaces the whole object, so it wipes anything set earlier: the `siteId` and `auth` in the Core Script on other platforms, or another snippet's hooks. The `...window.sparkOptions` line copies those across first. Every example in these docs extends the existing options, either with this spread or by adding to the object directly.

The spread keeps other settings, but a hook with the same name still replaces the earlier one. If two snippets need the same hook, combine them into one function, or keep a reference to the earlier hook and call it from yours, as the [chained checkout validation](https://docs.sparklayer.io/developers/javascript-sdk/checkout.md#combine-your-rule-with-existing-validation) example does.

For every option and hook, see [Options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md) and [Hooks](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md) in the SDK reference.

## Wait for SparkLayer to be ready

`window.spark` exists as soon as the Core Script runs, but its data isn't loaded until SparkLayer has started. Run your code from the `onReady` hook, which receives the `Spark` object once SparkLayer has initialised and the page's DOM has loaded. It runs whether or not the customer is logged in, so check with `isLoggedIn()` first:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onReady: async (spark) => {
    if (!(await spark.isLoggedIn())) {
      return;
    }
    // Safe to call spark methods here
  },
};
```

If your code can run after the Core Script has loaded (for example, from a script at the end of the page or in a separate app), use the `window.sparkReady` promise below instead. It resolves whether SparkLayer started before or after your code.

### Wait for SparkLayer from any script

Add this once, in your theme's `<head>` **before** the SparkLayer Core Script (on Shopify, before the SparkLayer app embed). It resolves `window.sparkReady` with `window.spark` when SparkLayer calls its `onReady` hook, and keeps any `onReady` you already have.

```html title="Theme <head>, before the SparkLayer script"
<script>
  (function () {
    var options = (window.sparkOptions = window.sparkOptions || {});
    var previous = options.onReady;
    var resolveReady;
    window.sparkReady = new Promise(function (resolve) {
      resolveReady = resolve;
    });
    options.onReady = async function (spark) {
      if (previous) await previous(spark);
      resolveReady(spark);
    };
  })();
</script>
```

Then, anywhere after it:

```javascript title="Any script"
const spark = await window.sparkReady;
```

Like the spread above, the snippet adds to `window.sparkOptions` instead of replacing it. Many examples on the other SDK pages start with `await window.sparkReady`, so add this snippet first.

## Manual initialisation (headless only)

On a headless storefront you may want to decide when SparkLayer starts, for example after your app has loaded the customer. If `window.sparkOptions` isn't set when the Core Script runs, SparkLayer doesn't start. Instead it defines `window.initSpark(options)`, which you call yourself:

```html title="Headless storefront"
<script>
  function startSparkLayer() {
    window.spark = window.initSpark({
      siteId: '<SITE_ID>',
      platform: 'shopify',
      auth: { user: 'customer@example.com', token: '<AUTH_TOKEN>' },
      onReady: async (spark) => {
        // SparkLayer is ready
      },
    });
  }
</script>
<script async src="https://sparkcdn.io/sparkjs/<SITE_ID>/live" onload="startSparkLayer()"></script>
```

Pass every option, including hooks, to `initSpark`. Don't set `window.sparkOptions` anywhere on the page (including with the `...window.sparkOptions` pattern), or SparkLayer starts automatically and `initSpark` isn't defined.

That rules out the [`window.sparkReady` snippet](#wait-for-sparklayer) too, because it sets `window.sparkOptions`. Pass an `onReady` hook to `initSpark` instead, and resolve your own promise from it. See [Headless and React](https://docs.sparklayer.io/developers/javascript-sdk/headless.md) for a full example.

## Next steps

- [Products and pricing](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md): Show a customer's price, RRP and price breaks in your own theme code.
- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Add, update and remove items, set cart fields and handle the results of updateCart.
- [SDK reference](https://docs.sparklayer.io/developers/javascript-sdk/reference.md): Every sparkOptions setting, hook, method and type.


---

# Products and pricing

URL: https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing

Show each B2B customer's own price, RRP and price breaks in your theme, price a quantity as it changes, and swap the product image when a variant is selected.

Show B2B prices in your own theme code, work out the price for a quantity, and keep your product images in step with SparkLayer's variant picker. This page uses the pricing methods below and the `spark-variant-change` event.

| Method | Use it to |
| --- | --- |
| [`getPricingForVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpricingforvariant) | Get a variant's price, RRP and price breaks for the logged-in customer. |
| [`getPriceForProduct()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpriceforproduct) | Get a product's "from" price across its variants, and how many prices there are. |
| [`calculatePricingForVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariant) | Price a quantity of a variant, including price breaks. |
| [`calculatePricingForVariantData()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariantdata) | Price a quantity from variant data you already have, without a request. |
| [`getPackSizeForVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpacksizeforvariant) | Get a variant's pack size (`1` if none is set). |
| [`getRrpPriceForVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getrrppriceforvariant) | Get a variant's RRP on its own. |

Each method takes your platform's parent product ID and the variant SKU. Prices are for the logged-in customer, so check `isLoggedIn()` first. Some examples use `window.sparkReady`: add the [Wait for SparkLayer](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#wait-for-sparklayer) snippet before them.

## Calculate the price for a quantity

This example calculates the price of two units of a variant once SparkLayer is ready:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onReady: async (spark) => {
    if (!(await spark.isLoggedIn())) {
      return;
    }

    // Parent product ID, variant SKU and quantity
    const pricing = await spark.calculatePricingForVariant('6660191387839', 'MUG-MOM', 2);
    console.log(pricing.totalPrice, pricing.unitPrice, pricing.currencyCode);
  },
};
```

`totalPrice` is the quantity × the unit price at that quantity, after any price breaks. See [`ProductVariantPricing`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#productvariantpricing) for every field.

## Show trade prices on your own product tiles

Your theme's collection tiles show retail prices. This swaps in each signed-in B2B customer's own price, with the RRP, and leaves retail visitors' prices alone. Give each tile its product ID and SKU:

```html title="Product tile (Shopify Liquid)"
<div class="tile" data-product-id="{{ product.id }}" data-sku="{{ product.selected_or_first_available_variant.sku }}">
  <span class="tile-price">{{ product.price | money }}</span>
  <span class="tile-rrp"></span>
</div>
```

```javascript title="Trade prices on tiles"
const money = (amount, currency) =>
  new Intl.NumberFormat(document.documentElement.lang || 'en-GB', {
    style: 'currency',
    currency,
  }).format(amount);

async function showTradePrices(root = document) {
  const spark = await window.sparkReady;
  if (!(await spark.isLoggedIn())) return; // retail visitors keep your normal prices

  const tiles = root.querySelectorAll('[data-product-id][data-sku]');
  await Promise.all(
    [...tiles].map(async (tile) => {
      try {
        const { price, rrp, currencyCode } = await spark.getPricingForVariant(
          tile.dataset.productId,
          tile.dataset.sku,
        );
        if (price === null) return; // no B2B price for this customer
        tile.querySelector('.tile-price').textContent = money(price, currencyCode);
        if (rrp) tile.querySelector('.tile-rrp').textContent = `RRP ${money(rrp, currencyCode)}`;
      } catch {
        // the product isn't available to this customer: leave the tile as it is
      }
    }),
  );
}

showTradePrices();
```

Call `showTradePrices(container)` again after your theme loads more products, for example on infinite scroll.

## Read the RRP metafield in Liquid

On Shopify, you can also render the RRP on the server, straight from the variant's `sparklayer.rrp` metafield. The metafield is JSON on the variant, with one entry per currency and decimal values (not subunits), for example `[{"value":9.00,"currency_code":"gbp"}]`. This snippet picks the entry for the shopper's currency, converts it to subunits for Shopify's `money` filter, and only shows it when it differs from the variant's Shopify price:

```liquid title="Product template (Shopify Liquid)"
{%- if customer.metafields.sparklayer.authentication -%}
  {%- assign variant = product.selected_or_first_available_variant -%}
  {%- for entry in variant.metafields.sparklayer.rrp.value -%}
    {%- assign entry_currency = entry.currency_code | upcase -%}
    {%- if entry_currency == cart.currency.iso_code -%}
      {%- assign rrp_subunits = entry.value | times: 100.0 | round -%}
      {%- if rrp_subunits != variant.price -%}
        <span class="b2b-rrp">RRP {{ rrp_subunits | money }}</span>
      {%- endif -%}
      {%- break -%}
    {%- endif -%}
  {%- endfor -%}
{%- endif -%}
```

- Liquid is rendered once, on the server. The RRP doesn't change when the customer picks another variant until the page reloads. For an RRP that follows the selected variant, use [`getRrpPriceForVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getrrppriceforvariant) or the `<spark-product-rrp>` [component](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#web-components).
- Shopify caches pages, so a change to the metafield can take a little while to show.

## Live price as the quantity changes

On a product page with your own quantity box, show the unit price, line total and price-break saving as the customer types, snapped to the product's pack size. It fetches the variant once, then works out each price instantly with `calculatePricingForVariantData`, so there's no request per keystroke.

```html title="Product page"
<input id="b2b-qty" type="number" min="1" value="1" data-product-id="{{ product.id }}" data-sku="{{ product.selected_or_first_available_variant.sku }}" />
<p id="b2b-line-price" aria-live="polite"></p>
```

```javascript title="Live quantity pricing"
const qtyInput = document.querySelector('#b2b-qty');
const output = document.querySelector('#b2b-line-price');
const { productId, sku } = qtyInput.dataset;

const money = (amount, currency) =>
  new Intl.NumberFormat(document.documentElement.lang || 'en-GB', {
    style: 'currency',
    currency,
  }).format(amount);

const spark = await window.sparkReady;
const [variant, packSize] = await Promise.all([
  spark.getVariant(productId, sku),
  spark.getPackSizeForVariant(productId, sku),
]);
qtyInput.step = String(packSize);
qtyInput.min = String(packSize);

function render() {
  // round up to a whole number of packs
  const qty = Math.max(packSize, Math.ceil((Number(qtyInput.value) || 1) / packSize) * packSize);
  const pricing = spark.calculatePricingForVariantData(variant, qty);
  if (pricing.unitPrice === null) {
    output.textContent = 'Price on request';
    return;
  }
  const saving = pricing.priceBreakSavingsPercentage
    ? ` (you save ${pricing.priceBreakSavingsPercentage}%)`
    : '';
  output.textContent = `${qty} × ${money(pricing.unitPrice, pricing.currencyCode)} = ${money(
    pricing.totalPrice,
    pricing.currencyCode,
  )}${saving}`;
}

qtyInput.addEventListener('input', render);
qtyInput.addEventListener('change', () => {
  qtyInput.value = String(Math.ceil((Number(qtyInput.value) || 1) / packSize) * packSize);
  render();
});
render();
```

Load this as a module (`<script type="module">`), so `await` works at the top level.

## Update the product image when a variant is selected

When a customer picks a variant in the `spark-pdp` or `spark-product-card` interface, SparkLayer doesn't change your theme's product image. You can do it with a little theme code:

1. Listen for the `spark-variant-change` event on each `spark-pdp` or `spark-product-card` element.
2. In the listener, show the image for the selected variant and hide the others.

### Listen for the event

`spark-variant-change` is dispatched on the interface element itself and doesn't bubble, so add a listener to each element. Register the listeners in `onReady`, once the elements are on the page:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onReady: async () => {
    for (const productCard of document.querySelectorAll('spark-product-card')) {
      productCard.addEventListener('spark-variant-change', (event) => {
        console.log(event.detail.product.externalId, event.detail.variant.externalId);
      });
    }
  },
};
```

`event.detail` has:

- `event.detail.product.externalId`: your platform's ID for the product (for example, the Shopify product ID).
- `event.detail.variant.externalId`: your platform's ID for the selected variant.

Elements added to the page later, such as by infinite scroll, need their own listeners.

### Show the variant's image

How you swap images depends on your theme's markup. This approach was tested with Shopify's Dawn theme:

1. Render every variant's image in the product card, for example by looping through the product's variants in the Liquid template. Hide all but the first variant's image, which is selected by default, with `style="opacity: 0"`.
2. Add a `data-variant-id` attribute to each variant image, set to the variant ID.
3. In the listener, hide every variant image in the card and show the one for the selected variant:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onReady: async () => {
    for (const productCard of document.querySelectorAll('spark-product-card')) {
      productCard.addEventListener('spark-variant-change', (event) => {
        const cardEl = event.target.closest('.card-wrapper');
        if (!cardEl) {
          return;
        }

        const variantId = event.detail.variant.externalId;

        // Hide all variant images
        for (const img of cardEl.querySelectorAll('img[data-variant-id]')) {
          img.style.opacity = '0';
        }

        // Show the selected variant's image
        const variantImg = cardEl.querySelector(`img[data-variant-id="${variantId}"]`);
        if (variantImg) {
          variantImg.style.opacity = '1';
        }
      });
    }
  },
};
```

The same code works for `spark-pdp`: change the selector and the wrapper class to match your product page.

## Next steps

- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Add products to the cart from your own buttons and forms, rounded to pack sizes.
- [Events and analytics](https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics.md): The hooks and DOM events you can run your own code from.
- [Pricing methods](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#products-and-pricing): Every product and pricing method, and the types they return.


---

# Cart

URL: https://docs.sparklayer.io/developers/javascript-sdk/cart

Add, update and remove cart items with updateCart, set PO numbers and cart fields, attach custom attributes and files, and open the cart drawer from code.

Change the B2B cart from your own code: add, update and remove items, read the cart back, set cart-level fields, attach custom attributes and files, and open the cart drawer. This page uses `updateCart`, `getCart`, `getCartCache`, `uploadFile`, `openDrawer` and `externalClearBasket`, and the `preCartUpdateListener` and `onCartUpdate` hooks.

`window.spark.updateCart` makes every change to the cart. Call it once SparkLayer is ready (see [Wait for SparkLayer to be ready](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#wait-for-sparklayer-to-be-ready)):

```typescript title="Type"
updateCart(
  input: Partial<UpdateCart>,
  cartSuccessHandledLocally?: boolean,
  cartErrorsHandledLocally?: boolean,
): Promise<CartResults[] | null>;
```

The input is an [`UpdateCart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#updatecart) object, and each product in it is a [`CartItemInput`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cartiteminput). Send only the fields you want to change.

## Add, update and remove items

Add a variant by SKU with `adjustQuantity`, which **increments** whatever quantity is already in the cart:

```javascript
await window.spark.updateCart({
  products: [{ sku: 'RED-SHIRT-M', adjustQuantity: 1 }],
});
```

Add several variants in one call:

```javascript
await window.spark.updateCart({
  products: [
    { sku: 'RED-SHIRT-M', adjustQuantity: 2 },
    { sku: 'BLUE-HAT-L', adjustQuantity: 1 },
  ],
});
```

Use `quantity` instead of `adjustQuantity` to **set** the line to an exact quantity rather than add to it, for example from a quantity input on the cart page:

```javascript
await window.spark.updateCart({
  products: [{ sku: 'RED-SHIRT-M', quantity: 5 }],
});
```

### Remove an item or clear the cart

Set `quantity` to `0` to remove a line. If you have the cart line's `itemKey` (from `getCart()`, for example), use it instead of the SKU:

```javascript
await window.spark.updateCart({
  products: [{ itemKey: 'abc123', quantity: 0 }],
});
```

Clear the whole cart:

```javascript
await window.spark.updateCart({ clearCart: true });
```

## Read the cart

`updateCart` returns the result for each line, not the cart. To read the cart, call `getCart()`, which fetches it, or `getCartCache()`, which returns the cached copy without a request (or `null` if there isn't one yet). Both return a [`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart).

This example adds a product to the cart, sets a custom field on the cart, then reads the cart back:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onReady: async (spark) => {
    if (!(await spark.isLoggedIn())) {
      return;
    }

    // Add 3 of a variant to the cart
    const results = await spark.updateCart({
      products: [{ sku: 'BRACE-COLOURED', adjustQuantity: 3 }],
    });
    console.log(results); // What was applied to each line

    // Set a custom field on the cart
    await spark.updateCart({
      customFields: [{ name: 'season', value: 'in-season' }],
    });

    console.log(await spark.getCart()); // The updated cart
  },
};
```

## Cart-level fields

Update `customerReference`, `poNumber`, `shippingRequestedDate` and `customFields` the same way, with or without `products`:

```javascript
await window.spark.updateCart({
  customerReference: 'This is a note on the order',
  poNumber: 'PO-4567',
});
```

`customerReference`, `poNumber` and `shippingRequestedDate` hold SparkLayer's standard checkout fields, and `customFields` holds your own.  To show these fields to customers at checkout, see [Checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md) in the Help Center.

## Custom attributes and files

Any product line can carry `customAttributes`: free-form key and value pairs that stay with the line through the cart and into the order, such as engraving text or a fabric choice. The `key` and `value` are shown to the customer and your staff under the line item.

- If you call `updateCart` yourself, such as from your own add-to-cart button, set `customAttributes` on the products you send: see [Add text](#add-text) and [Attach a file](#attach-a-file).
- To add attributes when a customer uses one of SparkLayer's own add-to-cart buttons (in the product detail or product card interface), you don't call `updateCart` yourself: use the [`preCartUpdateListener` hook](#add-attributes-to-sparklayers-add-to-cart) instead.

### Add text

To store text, set `value` to a string:

```javascript
await window.spark.updateCart({
  products: [
    {
      sku: 'SHIRT-CUSTOM',
      adjustQuantity: 1,
      customAttributes: [
        { key: 'Shirt Length', value: '32in' },
        { key: 'Shirt Fabric', value: 'Cotton' },
      ],
    },
  ],
});
```

### Attach a file

To attach a file, use the same array, but set `value` to a JSON string of an array of file GIDs. Upload the file with `spark.uploadFile()` to get its GID:

```javascript
const gid = await window.spark.uploadFile('design.png', fileBlob);

await window.spark.updateCart({
  products: [
    {
      sku: 'SHIRT-CUSTOM',
      adjustQuantity: 1,
      customAttributes: [
        { key: 'Design', value: JSON.stringify([gid]) },
      ],
    },
  ],
});
```

> **Match the file name to the file type**
>
> The file name you pass to `uploadFile()` (`design.png` above) must match the type of the data in `fileData`: don't name a JPEG `design.png`. A mismatch fails a check on the server after upload, the file is deleted, and the GID you got back stops working. Any later lookup of it errors, including reading the cart.

### Add attributes to SparkLayer's add to cart

`preCartUpdateListener` is a hook that runs just before one of SparkLayer's built-in add-to-cart buttons calls `updateCart`. It lets you change the update before it's sent: most often, to add custom attributes or files to the products.

```typescript title="Type"
preCartUpdateListener(input: Partial<UpdateCart>): Promise<Partial<UpdateCart>>;
```

`input` is the update about to be sent to `updateCart` (see [`UpdateCart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#updatecart)), not the current cart: it has no `items` or `totals`, only the products that interface is about to add. Return the update, changed or not, from an `async` function: SparkLayer sends whatever you return.

### Collect customisations from the page

The most common use is to read form fields on the product page and attach their values as `customAttributes` to the products being added. Tag each relevant `input` and `select` with `data-spark-custom-attributes`:

```html title="Product page"
<label for="shirt-length">Shirt Length</label>
<input id="shirt-length" name="Shirt Length" data-spark-custom-attributes />

<label for="shirt-fabric">Shirt Fabric</label>
<select id="shirt-fabric" name="Shirt Fabric" data-spark-custom-attributes>
  <option value="cotton">Cotton</option>
  <option value="polyester">Polyester</option>
</select>
```

Then collect the tagged fields in `preCartUpdateListener`. Each field's label (or its `name`, if it has no label) becomes the attribute's `key`:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  preCartUpdateListener: async (input) => {
    if (!input.products?.length) {
      return input;
    }

    const nodes = document.querySelectorAll(
      'input[data-spark-custom-attributes], select[data-spark-custom-attributes]',
    );

    const handledRadioGroups = new Set();
    const attrs = [];

    nodes.forEach((el) => {
      const type = (el.type || '').toLowerCase();

      if (type === 'radio') {
        if (handledRadioGroups.has(el.name)) return;
        handledRadioGroups.add(el.name);
        el = document.querySelector(
          `input[name="${CSS.escape(el.name)}"][data-spark-custom-attributes]:checked`,
        );
        if (!el) return; // nothing selected in this radio group
      } else if (type === 'checkbox' && !el.checked) {
        return;
      }

      const labelEl = el.id ? document.querySelector(`label[for="${CSS.escape(el.id)}"]`) : null;
      const key =
        labelEl?.textContent.trim().replace(/:$/, '') ||
        el.name;
      const value =
        el.tagName === 'SELECT'
          ? el.options[el.selectedIndex]?.textContent.trim()
          : el.value.trim();

      if (key && value) {
        attrs.push({ key, value });
      }
    });

    if (!attrs.length) {
      return input;
    }

    input.products.forEach((item) => {
      item.customAttributes = [...(item.customAttributes ?? []), ...attrs];
    });

    return input;
  },
};
```

For one or two fixed fields, it's simpler to read them directly:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  preCartUpdateListener: async (input) => {
    if (!input.products?.length) {
      return input;
    }

    const shirtLength = document.querySelector('#shirt-length')?.value;
    const shirtFabric = document.querySelector('#shirt-fabric')?.value;
    if (!shirtLength && !shirtFabric) {
      return input;
    }

    const customShirt = input.products.find((p) => p.sku === 'SHIRT-CUSTOM');
    if (!customShirt) {
      return input;
    }

    customShirt.customAttributes = customShirt.customAttributes ?? [];
    if (shirtLength) {
      customShirt.customAttributes.push({ key: 'Shirt Length', value: shirtLength });
    }
    if (shirtFabric) {
      customShirt.customAttributes.push({ key: 'Shirt Fabric', value: shirtFabric });
    }

    return input;
  },
};
```

### Let customers upload a file

Use the `spark-file-upload-field` web component to let customers upload a file, such as an image or design, on the product page. Then attach it with the same hook.

```html title="Product page"
<spark-file-upload-field
  id="shirt-design-upload"
  allowed-extensions='["png", "jpg", "jpeg"]'
></spark-file-upload-field>
```

| Attribute | Description |
| --- | --- |
| `allowed-extensions` | The file extensions to allow, as a JSON array. Defaults to the most common file extensions. |
| `max-file-size` | Maximum file size, in bytes. |
| `max-files` | Maximum number of files. |
| `required` | Whether a file must be uploaded. |

It dispatches two events, which bubble up to `window`:

- `spark-file-attachment-changed`: whenever the list of files changes. `event.detail` is an array of `{ fileSize, fileName, gid }`, or `null` if every file was removed.
- `spark-file-attachment-failed`: when a file fails to upload.

```javascript title="Listening for upload events"
window.addEventListener('spark-file-attachment-changed', (e) => {
  // e.detail is an array of the file details in the following format:
  // {
  //   fileSize: number,
  //   fileName: string,
  //   gid: string,
  // }

  // Handle files
});

window.addEventListener('spark-file-attachment-failed', (e) => {
  // e.detail format:
  // {
  //   fileSize: number,
  //   fileName: string,
  //   errorCode: string,
  // }
  //
  // errorCode can be one of the following:
  // - "unsupported-file-type"
  // - "file-too-large"
  // - "default"

  // Handle the failed file
});
```

`preCartUpdateListener` and the upload field usually live in different parts of your theme (`sparkOptions` in a layout file, the upload field in a product template), with no shared JavaScript scope. A hidden input is a simple way to pass the uploaded file data between them. Anything works, as long as `preCartUpdateListener` can read it when it runs.

Store the event detail in the hidden input, then use just the `gid`s as the custom attribute's `value`, in the same format as [Attach a file](#attach-a-file):

```html title="Product page"
<!-- holds the uploaded file data, written to and read back below -->
<input id="shirt-design" type="hidden" />

<script>
  {
    const uploadEl = document.querySelector('#shirt-design-upload'); // <-- id of the spark-file-upload-field above
    const inputEl = document.querySelector('#shirt-design');
    if (uploadEl && inputEl) {
      uploadEl.addEventListener('spark-file-attachment-changed', (e) => {
        inputEl.value = e.detail ? JSON.stringify(e.detail) : '';
      });
    }
  }
</script>
```

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  preCartUpdateListener: async (input) => {
    if (!input.products?.length) {
      return input;
    }

    const filesJson = document.querySelector('#shirt-design')?.value; // <-- read back the hidden input from above
    if (!filesJson) {
      return input;
    }

    const gids = JSON.parse(filesJson).map((file) => file.gid);

    const customShirt = input.products.find((p) => p.sku === 'SHIRT-CUSTOM'); // <-- match your own custom-line-item SKU
    if (!customShirt) {
      return input;
    }

    customShirt.customAttributes = [
      ...(customShirt.customAttributes ?? []),
      { key: 'Front Design', value: JSON.stringify(gids) }, // <-- key is shown to the customer/staff as the attachment's label
    ];

    return input;
  },
};
```

### Tag order lines with a campaign

Record which campaign brought a buyer in, as a custom attribute on every line they add, so it shows on the order. It reads `utm_campaign` from the landing page URL and keeps it for the visit. It also calls any `preCartUpdateListener` you already have, so it works alongside the examples above.

```html title="Theme <head>, before the SparkLayer script"
<script>
  (function () {
    var campaign = new URLSearchParams(window.location.search).get('utm_campaign');
    if (campaign) sessionStorage.setItem('b2bCampaign', campaign);

    var options = (window.sparkOptions = window.sparkOptions || {});
    var previous = options.preCartUpdateListener;

    options.preCartUpdateListener = async function (input) {
      var update = previous ? await previous(input) : input;
      var tag = sessionStorage.getItem('b2bCampaign');
      if (!tag || !update.products) return update;

      update.products = update.products.map(function (product) {
        return Object.assign({}, product, {
          customAttributes: (product.customAttributes || []).concat([{ key: 'Campaign', value: tag }]),
        });
      });
      return update;
    };
  })();
</script>
```

## Open the cart drawer

`openDrawer()` opens the SparkLayer drawer, on the Cart tab unless you pass another [tab](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#draweruistate). To open it each time the cart changes, call it from the `onCartUpdate` hook. This example also switches a drawer that's already open to the Cart tab:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onCartUpdate: async (cart, results) => {
    // Opens the drawer if it isn't already open
    window.spark.openDrawer('cart');

    // Switches an open drawer to the Cart tab
    window.dispatchEvent(
      new CustomEvent('view-update', {
        bubbles: true,
        composed: true,
        detail: { view: 'cart' },
      }),
    );
  },
};
```

## Handle the result and show feedback

### What updateCart returns

`updateCart` resolves to an array of [`CartResults`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cartresults), one for each product line you sent, or `null` if the request failed. It doesn't throw: on failure it shows an error toast and logs the error to the console.

Each result has:

- `requestedQuantity` and `resultantQuantity`: what you asked for and what was applied. They differ when one of the `messages` below applies, such as rounding to a pack size or limiting to the stock available.
- `itemKey`, `sku` and `name`: which line the result is for.
- `messages`: a list of `{ type }` objects for anything that happened to the line. `type` is one of:

| Type | Meaning |
| --- | --- |
| `success` | The line was added or updated with no issues. |
| `pack-size` | The quantity was rounded down to the nearest pack size. |
| `qty-excessive` | The quantity was lowered to the allowed maximum. |
| `qty-insufficient` | The quantity was raised to the allowed minimum. |
| `qty-unavailable` | The quantity was lowered to what's in stock. |
| `qty-unavailable-no-clamp` | The line was added, but the requested quantity isn't fully available. Check the cart. |
| `excessive-lines` | The cart's line limit was reached, so the item wasn't added. |
| `not-found` | The SKU doesn't exist. |
| `unavailable` | The product can't be bought at the moment. |
| `product-settings-overridden` | The product's default settings were overridden. |

These are status codes, not display text. `updateCart` uses them to show its own toasts (see below). If you show your own messages, switch on `type`.

### Show your own feedback

By default, `updateCart` shows toast messages. Pass `true` as the second argument (`cartSuccessHandledLocally`) to turn off the success toast, or as the third (`cartErrorsHandledLocally`) to turn off toasts for the `messages` in the results:

```javascript
// Suppress the built-in success toast, but keep automatic error toasts
await window.spark.updateCart(
  { products: [{ sku: 'RED-SHIRT-M', adjustQuantity: 1 }] },
  true, // cartSuccessHandledLocally
);
```

## Add to cart from your own button

Add a product to the B2B cart from any button, rounded up to its pack size, then open the cart drawer. SparkLayer shows its own messages if the quantity is changed, for example to match the stock available. This uses `window.sparkReady` from [Wait for SparkLayer](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#wait-for-sparklayer).

```html title="Any page"
<button type="button" data-add-to-trade-order data-product-id="{{ product.id }}" data-sku="{{ product.selected_or_first_available_variant.sku }}" data-qty="12">
  Add 12 to order
</button>
```

```javascript title="Add to cart"
document.addEventListener('click', async (event) => {
  const button = event.target.closest('[data-add-to-trade-order]');
  if (!button) return;

  const spark = await window.sparkReady;
  const { productId, sku } = button.dataset;
  const packSize = await spark.getPackSizeForVariant(productId, sku);
  const quantity = Math.ceil(Number(button.dataset.qty || 1) / packSize) * packSize;

  button.disabled = true;
  try {
    const results = await spark.updateCart({ products: [{ sku, adjustQuantity: quantity }] });
    if (results) spark.openDrawer('cart'); // null means SparkLayer already showed an error
  } finally {
    button.disabled = false;
  }
});
```

The click listener sits on `document`, so it also works for buttons your theme adds later.

## Quick order from a pasted list

Let buyers paste a list of SKUs and quantities, one per line, such as `MUG-BLUE 24` or `MUG-BLUE,24`, and add everything in one update. Duplicate SKUs are added together.

```html title="Quick order form"
<form id="quick-order">
  <label for="quick-order-lines">SKUs and quantities, one per line</label>
  <textarea id="quick-order-lines" rows="8" placeholder="MUG-BLUE 24&#10;MUG-RED, 12"></textarea>
  <button type="submit">Add to order</button>
  <p id="quick-order-result" aria-live="polite"></p>
</form>
```

```javascript title="Quick order"
document.querySelector('#quick-order').addEventListener('submit', async (event) => {
  event.preventDefault();
  const text = document.querySelector('#quick-order-lines').value;
  const result = document.querySelector('#quick-order-result');

  const totals = new Map();
  const skipped = [];
  for (const line of text.split('\n').map((l) => l.trim()).filter(Boolean)) {
    const [sku, qty] = line.split(/[\s,;\t]+/);
    const quantity = Number.parseInt(qty ?? '1', 10);
    if (!sku || !Number.isFinite(quantity) || quantity < 1) {
      skipped.push(line);
      continue;
    }
    totals.set(sku, (totals.get(sku) ?? 0) + quantity);
  }
  if (!totals.size) {
    result.textContent = 'Add at least one SKU and quantity.';
    return;
  }

  const spark = await window.sparkReady;
  const products = [...totals].map(([sku, adjustQuantity]) => ({ sku, adjustQuantity }));
  const results = await spark.updateCart({ products });
  if (!results) return; // SparkLayer showed the error

  const added = results.filter((r) => r.resultantQuantity > 0).length;
  result.textContent = `Added ${added} of ${products.length} products.${
    skipped.length ? ` Couldn't read: ${skipped.join(', ')}.` : ''
  }`;
  spark.openDrawer('cart');
});
```

## Clear the cart after an order

If customers complete orders outside SparkLayer's checkout and your order confirmation page loads the Core Script, clear their B2B cart there:

```javascript title="Order confirmation page"
const spark = await window.sparkReady;
await spark.externalClearBasket();
```

## Next steps

- [Checkout](https://docs.sparklayer.io/developers/javascript-sdk/checkout.md): Check the cart against your own rules before the customer can check out.
- [Products and pricing](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md): Show trade prices and live quantity pricing in your theme.
- [Cart types](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart): The UpdateCart, CartItemInput, CartResults and Cart types in full.


---

# Checkout

URL: https://docs.sparklayer.io/developers/javascript-sdk/checkout

Block SparkLayer checkout until your own rules are met with the onCheckoutValidation hook, from a simple product quota check to rules chained together.

Add your own rules to SparkLayer's checkout, for rules SparkLayer's own settings don't cover. This page uses the `onCheckoutValidation` hook, with examples that call your own API and that combine several rules.

## Add custom checkout validation

`onCheckoutValidation` lets you check the cart against your own rules, or your own API, before the customer can check out. For example, you could check whether a customer has already used up a one-off discount or a product quota, or limit how many free samples go in one order.

The hook must be an `async` function. It receives the [`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart) and the current checkout step (a [`CartUIState`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cartuistate), so your rules can vary by step), and returns `null` if the cart is valid or an array of `{ message }` objects if it isn't.

SparkLayer shows each `message` to the customer and won't let them check out until the hook returns `null`.  The hook runs every time the cart loads or changes, so keep it quick: avoid network requests unless your rule needs them, and keep any you make fast.

### Check the cart against your API

This example sends the cart to your own endpoint and blocks checkout if it says the cart isn't valid:

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onCheckoutValidation: async (cart, cartUiState) => {
    const response = await fetch('https://example.com/cart-validation', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(cart),
    });
    const { valid } = await response.json();

    if (valid) {
      return null;
    }

    return [{ message: 'This order is over your quota for one of these products.' }];
  },
};
```

Decide what should happen if your API is unreachable. Here, a failed request rejects the promise: SparkLayer logs the error to the console and doesn't apply a result.

### Combine your rule with existing validation

Setting `onCheckoutValidation` replaces any hook another snippet has set. To add a rule without losing one that's already there, keep a reference to the earlier hook, call it, and add your messages to its list. This example limits free samples to three per order:

```html title="Theme <head>, before the SparkLayer script"
<script>
  (function () {
    var options = (window.sparkOptions = window.sparkOptions || {});
    var previous = options.onCheckoutValidation;

    options.onCheckoutValidation = async function (cart, cartUiState) {
      var errors = (previous && (await previous(cart, cartUiState))) || [];

      var samples = cart.items
        .filter(function (item) {
          return item.sku && item.sku.indexOf('SAMPLE-') === 0;
        })
        .reduce(function (total, item) {
          return total + item.quantity;
        }, 0);

      if (samples > 3) {
        errors.push({
          message: 'You can order up to 3 samples per order. Remove ' + (samples - 3) + ' to continue.',
        });
      }
      return errors.length ? errors : null;
    };
  })();
</script>
```

## Collect extra details at checkout

To ask customers for a PO number, a requested delivery date or your own fields at checkout, turn on [checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md) in the Help Center, or set them in code with the [`checkoutCustomElements`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) option. To fill these values in from your own code, see [Cart-level fields](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#cart-level-fields).

## Next steps

- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Add and remove items, set cart-level fields and handle the results of updateCart.
- [Checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md): Turn on standard checkout fields and add your own.
- [onCheckoutValidation](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncheckoutvalidation): The hook's signature and return value, with links to the Cart and CartUIState types.


---

# Customers and accounts

URL: https://docs.sparklayer.io/developers/javascript-sdk/customers-and-accounts

Check whether a B2B customer is logged in, switch customers as a sales agent, change company section, refresh customer data and run GraphQL queries.

Work with the logged-in customer from your own code: check the login, act for a customer as a sales agent, switch company section, refresh their data and query the GraphQL API. This page uses `isLoggedIn`, `switchImpersonatingCustomer`, `setActiveCompanySection`, `refreshGlobalData`, `getActiveCustomerVerificationToken` and `fetch`, plus the `spark-redirect.js` login redirect.

The examples use `window.sparkReady`: add the [Wait for SparkLayer](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#wait-for-sparklayer) snippet before them. For every method's parameters and return values, see [Customers and session](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#customers-and-session) in the SDK methods.

## Check whether the customer is logged in

`isLoggedIn()` resolves to `true` when the customer is logged in to SparkLayer. The `onReady` hook runs for every visitor, so check it before you show B2B content or call pricing and cart methods:

```javascript title="Any script"
const spark = await window.sparkReady;

if (await spark.isLoggedIn()) {
  // Show B2B content
}
```

## Switch the customer a sales agent orders for

A [sales agent](https://docs.sparklayer.io/help/sales-reps.md) can order on behalf of their customers. `switchImpersonatingCustomer()` changes the customer they're acting for, and `null` ends impersonation. Both resolve to the [`UserData`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#userdata) for the active customer, or `null`.

```javascript title="Any script"
const spark = await window.sparkReady;

// Act for a customer
const customer = await spark.switchImpersonatingCustomer('<CUSTOMER_ID>');

// End impersonation
await spark.switchImpersonatingCustomer(null);
```

While a sales agent is impersonating, pass `true` as the `useImpersonatingCustomer` argument of [`fetch()`](#run-a-graphql-query) to run a query as the impersonated customer rather than the sales agent.

## Select a company section

If a customer's company is split into sections, `setActiveCompanySection()` selects the one they're buying for. If the cart isn't empty, the customer is asked to confirm and the cart is cleared, then the page reloads. It resolves to `false` if the section isn't available to the customer, they cancel, or the cart couldn't be cleared.

```javascript title="Any script"
const spark = await window.sparkReady;
const user = await spark.refreshGlobalData();
const section = user?.companySections[0];

if (section && !(await spark.setActiveCompanySection(section.id))) {
  // The section wasn't changed
}
```

## Refresh customer and site data

SparkLayer caches the active customer and the site configuration. If they change while the page is open, for example after your own code updates the customer through the API, call `refreshGlobalData()` to fetch them again. It resolves to the active customer's [`UserData`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#userdata), or `null`.

```javascript title="Any script"
const spark = await window.sparkReady;
const user = await spark.refreshGlobalData();
```

## Get a customer verification token

`getActiveCustomerVerificationToken()` refetches the active customer and resolves to a fresh form customer verification token, or `null`. When a sales agent is impersonating, the token is for the impersonated customer; otherwise it's for the logged-in customer.

```javascript title="Any script"
const spark = await window.sparkReady;
const token = await spark.getActiveCustomerVerificationToken();
```

## Run a GraphQL query

`spark.fetch` runs a GraphQL query as the signed-in customer. This one reads their email address:

```javascript title="GraphQL query"
const spark = await window.sparkReady;
const response = await spark.fetch(`query {
  loggedInCustomer {
    id
    email
  }
}`);

if (response.status === 200) {
  const { data, errors } = await response.json();
  if (!errors?.length) console.log(data.loggedInCustomer.email);
}
```

`fetch` returns a standard `Response`: check `status`, then call `json()` for the `data` and `errors`. See [fetch()](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch) for its other arguments.

## Redirect to the login page

`spark-redirect.js` sends customers who aren't logged in to your login page when they follow a link that needs SparkLayer, such as the **View order** button in some emails. This lets SparkLayer open what the link was for once they've logged in.

Add it to your theme in addition to the Core Script. On Shopify, put it outside the `{%- if customer.metafields.sparklayer.authentication -%}` block, so it loads for customers who aren't logged in:

```html title="theme.liquid"
<script async src="https://cdn.sparklayer.io/spark-redirect.js"></script>
```

By default, customers are sent to `/account/login`. To use another path, set `window.sparkRedirectLoginPath` before the script:

```html title="theme.liquid"
<script>
  window.sparkRedirectLoginPath = '/account/login';
</script>
<script async src="https://cdn.sparklayer.io/spark-redirect.js"></script>
```

## Next steps

- [Events and analytics](https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics.md): Run your code when the customer logs out, the cart changes or SparkLayer is ready.
- [Sales rep setup](https://docs.sparklayer.io/help/sales-reps.md): Add sales agents and choose which customers they can order for.
- [Customer methods](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#customers-and-session): Every customer and session method, and the UserData type.


---

# Events and analytics

URL: https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics

Run your own code from SparkLayer's hooks and DOM events, send B2B events to Google Analytics or Tag Manager, and push cart changes to any analytics tool.

Run your own code at key moments in SparkLayer, react to what customers do in its interfaces, and send B2B events to your analytics. This page covers the `onLoad`, `onReady`, `onCartLoad`, `onCartUpdate` and `onLogout` hooks, SparkLayer's DOM events and web components, and the `analytics` option.

## Hooks

Hooks are `async` functions you set on `window.sparkOptions` before the Core Script loads (see [Add your own options and hooks](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#add-your-own-options-and-hooks)). SparkLayer calls them at these points:

| Hook | When it runs | Receives |
| --- | --- | --- |
| [`onLoad`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onload) | Once while SparkLayer initialises, after translations have loaded and before `onReady`, whether or not the customer is logged in. | The `Spark` object |
| [`onReady`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onready) | When SparkLayer has initialised and the page's DOM has loaded. The place to start most of your code. | The `Spark` object |
| [`onCartLoad`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncartload) | When the cart is loaded. | The `Cart` |
| [`onCartUpdate`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncartupdate) | Each time the cart is updated. | The updated `Cart` and the `CartResults` for each change |
| [`onLogout`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onlogout) | When the customer logs out. | Nothing |

Two more hooks change what SparkLayer does rather than react to it: `preCartUpdateListener` edits an update before SparkLayer's add to cart sends it (see [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#add-attributes-to-sparklayers-add-to-cart)), and `onCheckoutValidation` blocks checkout (see [Checkout](https://docs.sparklayer.io/developers/javascript-sdk/checkout.md)).

If `onReady`, `onCartLoad` or `onCartUpdate` throws an error, SparkLayer shows a system error with a code that names the hook. See [Hook error codes](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#hook-error-codes).

## DOM events and web components

SparkLayer's interfaces are web components, such as `<spark-pdp>` and `<spark-product-card>`, that you add to your theme. Some of them dispatch DOM events you can listen for:

- `spark-variant-change`: the customer selects a variant in `spark-pdp` or `spark-product-card`. It doesn't bubble, so listen on each element. See [Update the product image when a variant is selected](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md#update-the-product-image-when-a-variant-is-selected).
- `spark-file-attachment-changed` and `spark-file-attachment-failed`: a file is added to, removed from or fails to upload to a `spark-file-upload-field`. See [Let customers upload a file](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#let-customers-upload-a-file).
- `view-update`: you dispatch this one on `window` to switch an open drawer to a tab. See [Open the cart drawer](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#open-the-cart-drawer).

For every web component and event, with the shape of each `event.detail`, see [Events and components](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md) in the SDK reference.

## Google Analytics

SparkLayer can send B2B events, such as add to cart, begin checkout and purchase, to Google Analytics (GA4), Google Tag Manager or your own function. You turn this on with the `analytics` option in `sparkOptions`, listing a `handler` and the `events` to send for each provider.

For the configuration, the list of events and a custom handler example, see [Event tracking for analytics](https://docs.sparklayer.io/developers/frontend/technical-information.md#event-tracking-for-analytics-google-analytics-ga4).

## Send cart changes to your analytics

For tools other than [Google Analytics](#google-analytics), push cart changes to the data layer from the `onCartUpdate` hook. This snippet keeps any `onCartUpdate` you already have:

```html title="Theme <head>, before the SparkLayer script"
<script>
  (function () {
    var options = (window.sparkOptions = window.sparkOptions || {});
    var previous = options.onCartUpdate;

    options.onCartUpdate = async function (cart, results) {
      if (previous) await previous(cart, results);
      window.dataLayer = window.dataLayer || [];
      (results || []).forEach(function (result) {
        window.dataLayer.push({
          event: 'b2b_cart_change',
          sku: result.sku,
          name: result.name,
          quantity: result.resultantQuantity,
          currency: cart.currencyCode,
        });
      });
    };
  })();
</script>
```

## Next steps

- [Event tracking for analytics](https://docs.sparklayer.io/developers/frontend/technical-information.md#event-tracking-for-analytics-google-analytics-ga4): Turn on GA4 or Google Tag Manager, and see every event SparkLayer sends.
- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Change the cart from your own code and open the cart drawer.
- [Hooks](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md): When each hook runs, what it receives and returns, with an example of each.


---

# Headless and React

URL: https://docs.sparklayer.io/developers/javascript-sdk/headless

Run SparkLayer on a headless storefront: load the Core Script, start it with initSpark, authenticate the customer, and use it from Next.js and React.

On a headless storefront, your own frontend renders the pages, so it also loads SparkLayer: it fetches the logged-in customer, loads the Core Script and starts SparkLayer with `window.initSpark()`. This page walks through a headless Shopify storefront built with Next.js, using `window.initSpark()` and the `onReady` and `onLogout` options, then shows a React hook for calling `window.spark` from your components.

SparkLayer still needs your platform's data (products, customers and orders) to stay in sync. On Shopify, the SparkLayer app does this. For another platform or a custom backend, [SparkLayer Ignite](https://docs.sparklayer.io/ignite.md) connects it to SparkLayer. 

## Requirements

- **A Shopify store** with the [SparkLayer app](https://apps.shopify.com/sparklayer) installed.
- **A metafield definition** for the SparkLayer authentication customer metafield (`sparklayer.authentication`).
- **Storefront access** turned on for that metafield definition, so your frontend can read it.

SparkLayer stores each customer's authentication data in this metafield. Your frontend passes it to SparkLayer, which uses it to authenticate the customer with the SparkLayer API.

## How it works

1. Get the logged-in customer's data.
2. Check that they're a B2B customer (in this example, tagged `b2b`) and have the `sparklayer.authentication` metafield set. If not, don't load SparkLayer.
3. Load the Core Script by adding a script tag: `<script async src="https://sparkcdn.io/sparkjs/<SITE_ID>/live"></script>`.
4. Once the script has loaded, call `window.initSpark({ … })` with your options, such as `siteId`, `platform` and `auth`. See [Options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md).
5. Add a `<style>` element that sets SparkLayer's CSS variables, to match the interfaces to your design. See [Customising the design](https://docs.sparklayer.io/help/storefront/customising-design.md).

Don't set `window.sparkOptions` on a headless site. If it's set when the Core Script runs, SparkLayer starts automatically and `window.initSpark` isn't defined.

You'll also need to add SparkLayer's interfaces, hide elements B2B customers shouldn't see, and connect SparkLayer to controls on your site, such as the cart and account buttons.

## Hide elements from B2B customers

Hide these elements from B2B customers on every page:

- Prices
- Add to cart buttons
- Quantity selectors

Add `data-spark="b2c-only"` to an element and SparkLayer hides it once it loads for a B2B customer. See [Hiding elements](https://docs.sparklayer.io/developers/frontend.md#hiding-elements).

## Add SparkLayer's interfaces

Add SparkLayer's interfaces in place of the elements you've hidden. How you output the parent product ID depends on your templating system; the examples below use a `{{ parentProductId }}` placeholder.

### Product card

```html title="Product list"
<spark-product-card parent-id="{{ parentProductId }}"></spark-product-card>
```

See [Product card](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) for its settings.

### Product detail page

```html title="Product detail page"
<spark-pdp parent-id="{{ parentProductId }}"></spark-pdp>
```

See [Product detail](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) for its settings.

## Load SparkLayer in Next.js

This React component loads SparkLayer in a Next.js project. It adds the Core Script only for B2B customers, then calls `initSpark` once the script has loaded and the authentication metafield is available:

```jsx title="SparkLayer.jsx"
import { useState, useEffect } from 'react';
import Script from 'next/script';

const defaultStyles = `
/* Size SparkLayer's web components to fit your design */
spark-product-card {
  width: 100%;
}
spark-pdp {
  margin: 0.5em 0 1.25em;
  display: block;
}

/* Set CSS variables to style the elements inside SparkLayer's web components */
:root {
  --b2b-brand-color: var(--primary);             /* Main brand colour */
  --b2b-brand-color-hover: var(--secondary);     /* Main brand colour on hover */
  --b2b-brand-font: Poppins, sans-serif;         /* Main brand font */
  --b2b-brand-font-heading: Poppins, sans-serif; /* Main brand heading font */

  /* For more variables, see https://docs.sparklayer.io/help/storefront/customising-design */
}`;

const defaultOptions = {
  platform: 'shopify',
  shopify: {
    useAppProxy: false,
  },
  cartButtonSelectors: '', // CSS selector for the cart button, usually in the header
  accountButtonSelectors: '', // CSS selector for the account button, usually in the header
};

export function SparkLayer(props) {
  const {
    customer,
    authenticationMetafield,
    options,
    onLogout,
    styles = defaultStyles,
  } = props;

  const sparkOptions = { ...defaultOptions, ...options };

  const [sparkInitialised, setSparkInitialised] = useState(false);
  const [sparkLoaded, setSparkLoaded] = useState(false);

  useEffect(() => {
    if (
      !sparkInitialised &&
      customer !== null &&
      authenticationMetafield.finished &&
      sparkLoaded &&
      !window.spark
    ) {
      const style = document.createElement('style');
      style.textContent = styles;
      document.head.appendChild(style);

      window.spark = window.initSpark({
        ...sparkOptions,
        onLogout,
        auth: {
          user: customer?.email,
          token: authenticationMetafield.metafield?.value,
        },
      });
      setSparkInitialised(true);
    }
  }, [customer, authenticationMetafield, sparkLoaded]);

  return customer !== null && customer.tags.includes('b2b') ? (
    <Script
      id="spark-script"
      src={`https://sparkcdn.io/sparkjs/${sparkOptions.siteId}/live`}
      onLoad={() => {
        setSparkLoaded(true);
      }}
    />
  ) : null;
}
```

Use the component in your layout, passing in the customer and their authentication metafield:

```jsx title="Layout.jsx"
import { SparkLayer } from '../snippets/Integrations/SparkLayer';

function Layout({ children }) {
  // Your app provides the logged-in customer's data
  const customer = getCustomer();

  // Your app provides the logged-in customer's Shopify metafields
  const authenticationMetafield = getCustomerMetafield('sparklayer.authentication');

  return (
    <div>
      <SparkLayer
        options={{
          siteId: '<SITE_ID>',
        }}
        onLogout={() => {
          // Log the customer out with your app's own function
          logout();
        }}
        authenticationMetafield={authenticationMetafield}
        customer={customer}
      />
      {children}
    </div>
  );
}

export default Layout;
```

If your app renders pages on the client, your cart and account buttons may lose SparkLayer's click handlers when your header re-renders. Open the drawer from your own buttons instead, with [`openDrawer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer), for example `window.spark.openDrawer('account')`.

To talk through a headless build with our team, [get in touch](https://docs.sparklayer.io/help/support.md).

## Use SparkLayer in React

A small hook that waits for SparkLayer and re-renders once it's ready. It's safe with server rendering, because it only touches `window` in an effect.

```tsx title="useSpark.ts"
import { useEffect, useState } from 'react';

// Spark is the type from spark.d.ts: /developers/javascript-sdk/reference/types#spark
declare global {
  interface Window {
    sparkReady?: Promise<Spark>;
  }
}

export function useSpark(): Spark | null {
  const [spark, setSpark] = useState<Spark | null>(null);

  useEffect(() => {
    let active = true;
    window.sparkReady?.then((ready) => {
      if (active) setSpark(ready);
    });
    return () => {
      active = false;
    };
  }, []);

  return spark;
}
```

```tsx title="TradePrice.tsx"
import { useEffect, useState } from 'react';
import { useSpark } from './useSpark';

export function TradePrice({ productId, sku }: { productId: string; sku: string }) {
  const spark = useSpark();
  const [label, setLabel] = useState<string | null>(null);

  useEffect(() => {
    if (!spark) return;
    spark
      .getPricingForVariant(productId, sku)
      .then(({ price, currencyCode }) => {
        if (price === null) return;
        setLabel(new Intl.NumberFormat(undefined, { style: 'currency', currency: currencyCode }).format(price));
      })
      .catch(() => setLabel(null));
  }, [spark, productId, sku]);

  return label ? <span className="trade-price">{label}</span> : null;
}
```

The hook reads `window.sparkReady`, so something must create that promise before your components render:

- If SparkLayer starts on its own (with `window.sparkOptions`), add the [Wait for SparkLayer](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#wait-for-sparklayer) snippet before the SparkLayer script, for example in your root layout's `<head>`.
- If you start SparkLayer with `initSpark`, as in the Next.js example above, don't use that snippet: it sets `window.sparkOptions`. Create `window.sparkReady` yourself before your components render, and resolve it from the `onReady` option you pass to `initSpark`.

## Next steps

- [Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md): How the SDK loads, how to wait for it to be ready, and manual initialisation.
- [SDK reference](https://docs.sparklayer.io/developers/javascript-sdk/reference.md): Every option you can pass to initSpark, plus each hook, method and type.
- [Frontend integration](https://docs.sparklayer.io/developers/frontend.md): The Core Script, the product page interfaces and hiding elements from B2B customers.


---

# SDK reference

URL: https://docs.sparklayer.io/developers/javascript-sdk/reference

Look up every sparkOptions setting, hook, window.spark method, DOM event and web component in the SparkLayer JavaScript SDK, and download its types.

You set [`window.sparkOptions`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md) before the Core Script loads, and SparkLayer then sets [`window.spark`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md), the object with every method. On a [headless storefront](https://docs.sparklayer.io/developers/javascript-sdk/headless.md), leave `window.sparkOptions` unset and call `window.initSpark(options)` yourself: it takes the same options and returns the same object.

For worked examples, start with [Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md).

## Options

The settings on `window.sparkOptions`. Only `siteId` is required.

**Site and platform**

| Option | What it does |
| --- | --- |
| [`siteId`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#site-and-platform) | Your site ID. Required. |
| [`sparkDomain`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#site-and-platform) | The domain of the SparkLayer API. |
| [`platform`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#site-and-platform) | Sets the default options for your ecommerce platform. |
| [`rootUrl`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#site-and-platform) | Prefixes the URLs SparkLayer creates, generally for i18n. |
| [`wordpressSiteUrl`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#site-and-platform) | The WordPress site URL, on WooCommerce. |
| [`shopify`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#site-and-platform) | Shopify options: whether to use the app proxy. |
| [`bigcommerce`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#site-and-platform) | BigCommerce options: your app client ID. |

**Links and redirects**

| Option | What it does |
| --- | --- |
| [`accountRedirect`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#links-and-redirects) | Sends logged-in users from matching paths to a page with the account drawer open. |
| [`cartRedirect`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#links-and-redirects) | Sends logged-in users from matching paths to a page with the cart drawer open. |
| [`termsAndConditionsLink`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#links-and-redirects) | Link to your terms and conditions. |
| [`productLink`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#links-and-redirects) | The link to a product page, built from the product's slug. |

**Button selectors**

| Option | What it does |
| --- | --- |
| [`accountButtonSelectors`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#button-selectors) | CSS selectors for the account button. |
| [`logoutButtonSelectors`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#button-selectors) | CSS selectors for the logout button. |
| [`cartButtonSelectors`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#button-selectors) | CSS selectors for the cart button. |
| [`loginButtonSelectors`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#button-selectors) | CSS selectors for the login button. |

**Display, language and translations**

| Option | What it does |
| --- | --- |
| [`display`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#display-language-and-translations) | Display options, such as the dark theme, SKUs and My Account sections. |
| [`language`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#display-language-and-translations) | The language SparkLayer uses. |
| [`locale`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#display-language-and-translations) | The locale for formatting dates. |
| [`translations`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#display-language-and-translations) | Overrides SparkLayer's text, by language. |
| [`showTranslations`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#display-language-and-translations) | Shows translation keys instead of text, for debugging. |

**Checkout and account**

| Option | What it does |
| --- | --- |
| [`checkoutCustomElements`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) | Standard and custom fields to show in checkout. |
| [`paymentMethodsOrder`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) | The order of the payment methods. |
| [`saveToAddressBookDefault`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) | Whether new addresses are saved to the address book by default. |
| [`customAccountDetails`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) | Extra details to show on a customer's My Details panel. |
| [`igniteCheckoutContext`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) | Checkout context data to pass to Ignite. |

**Authentication and analytics**

| Option | What it does |
| --- | --- |
| [`auth`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#authentication-and-analytics) | The user and token for SparkLayer auth. |
| [`authLogoutUri`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#authentication-and-analytics) | Where SparkLayer redirects after logging out. |
| [`analytics`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#authentication-and-analytics) | The analytics providers and events to send. |

## Hooks

Functions you set on `window.sparkOptions`, which SparkLayer calls.

| Hook | When it runs |
| --- | --- |
| [`onReady`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onready) | When SparkLayer has initialised and the page's DOM has loaded. |
| [`onLoad`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onload) | Once while SparkLayer initialises, before `onReady`. |
| [`onLogout`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onlogout) | When the user logs out. |
| [`onCartLoad`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncartload) | When the cart is loaded. |
| [`onCartUpdate`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncartupdate) | Each time the cart is updated. |
| [`preCartUpdateListener`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#precartupdatelistener) | Just before SparkLayer's add to cart updates the cart, to change the update. |
| [`onCheckoutValidation`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncheckoutvalidation) | Each time the cart loads or changes, to block checkout. |

If a hook throws, SparkLayer shows a [hook error code](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#hook-error-codes).

## Methods

The methods on `window.spark`. Call them once SparkLayer is ready.

**Customers and session**

| Method | What it does | Returns |
| --- | --- | --- |
| [`isLoggedIn()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#isloggedin) | Checks whether the user is logged in. | `Promise<boolean>` |
| [`switchImpersonatingCustomer(customerId)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#switchimpersonatingcustomer) | Switches the customer a sales agent acts for, or ends it with `null`. | `Promise<UserData \| null>` |
| [`refreshGlobalData()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#refreshglobaldata) | Refetches the active customer and site configuration. | `Promise<UserData \| null>` |
| [`getActiveCustomerVerificationToken()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getactivecustomerverificationtoken) | Gets a fresh form customer verification token. | `Promise<string \| null>` |
| [`setActiveCompanySection(sectionId)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#setactivecompanysection) | Selects the company section to buy for, then reloads. | `Promise<boolean>` |

**Products and pricing**

| Method | What it does | Returns |
| --- | --- | --- |
| [`getProduct(parentProductId)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getproduct) | Fetches a product by its parent product ID. | `Promise<Product>` |
| [`getProductBySlug(slug)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getproductbyslug) | Fetches a product by its slug. | `Promise<Product>` |
| [`getVariant(parentProductId, variantSku)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getvariant) | Fetches a variant. | `Promise<ProductVariant>` |
| [`getPriceForProduct(parentProductId)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpriceforproduct) | Gets a product's "from" price and how many prices it has. | `Promise<SimplifiedProductPrice>` |
| [`getPricingForVariant(parentProductId, variantSku)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpricingforvariant) | Gets a variant's price, RRP and price breaks. | `Promise<{ price, rrp, … }>` |
| [`getRrpPriceForVariant(parentProductId, variantSku)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getrrppriceforvariant) | Gets a variant's RRP. | `Promise<{ rrp, currencyCode }>` |
| [`getPackSizeForVariant(parentProductId, variantSku)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpacksizeforvariant) | Gets a variant's pack size. | `Promise<number>` |
| [`calculatePricingForVariant(parentProductId, variantSku, qty)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariant) | Prices a quantity of a variant. | `Promise<ProductVariantPricing>` |
| [`calculatePricingForVariantData(variant, qty)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariantdata) | Prices a quantity from variant data you have, without a request. | `ProductVariantPricing` |

**Cart**

| Method | What it does | Returns |
| --- | --- | --- |
| [`getCart()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getcart) | Fetches the cart. | `Promise<Cart \| null>` |
| [`getCartCache()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getcartcache) | Gets the cached cart, without a request. | `Cart \| null` |
| [`updateCart(input)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#updatecart) | Adds, updates or removes items and sets cart fields. | `Promise<CartResults[] \| null>` |
| [`addCustomLineItem(customItem)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#addcustomlineitem) | Adds a line not tied to a SKU. | `Promise<Cart \| null>` |
| [`externalClearBasket()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#externalclearbasket) | Clears the cart, for your order confirmation page. | `Promise<void>` |

**Drawer**

| Method | What it does | Returns |
| --- | --- | --- |
| [`openDrawer(initialTab)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer) | Opens the drawer, on the Cart tab unless you pass another. | `void` |
| [`closeDrawer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#closedrawer) | Closes the drawer. | `void` |

**Files and GraphQL**

| Method | What it does | Returns |
| --- | --- | --- |
| [`uploadFile(fileName, fileData)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#uploadfile) | Uploads a file to attach to a cart line. | `Promise<string>` |
| [`fetch(query, variables)`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch) | Runs a GraphQL query or mutation as the user. | `Promise<FetchResponse>` |

`window.spark.options` holds the [options](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#options) SparkLayer is running with.

## Events and components

| Name | What it is |
| --- | --- |
| [`spark-variant-change`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#spark-variant-change) | Event: the customer selects a variant in `spark-pdp` or `spark-product-card`. |
| [`spark-file-attachment-changed`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#spark-file-attachment-changed) | Event: the files in a `spark-file-upload-field` change. |
| [`spark-file-attachment-failed`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#spark-file-attachment-failed) | Event: a file fails to upload. |
| [`view-update`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#view-update) | Event you dispatch to switch an open drawer to a tab. |
| [`<spark-pdp>`, `<spark-product-card>`, `<spark-product-matrix>`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#web-components) | Components: the product detail, product card and product matrix interfaces. |
| [`<spark-product-price>`, `<spark-product-rrp>`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#web-components) | Components: the customer's price or the RRP for a product, anywhere on the page. |
| [`<spark-file-upload-field>`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#web-components) | Component: a file upload field for the product page. |
| [`<spark-drawer>`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#web-components) | Component: the drawer, which SparkLayer adds when needed. |

## TypeScript types

Download [spark.d.ts](https://docs.sparklayer.io/developers/javascript-sdk/spark.d.ts) for autocomplete and type checking in your editor, or point your AI assistant at it. It's generated from the [Types](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md) page.

```typescript title="cart.ts"
/// <reference path="./spark.d.ts" />

export async function countCartLines() {
  const cart = await window.spark.getCart(); // Cart | null
  return cart?.items.length ?? 0;
}
```

## Next steps

- [Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md): How the SDK loads, how to add your options and hooks, and how to wait for it.
- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Add, update and remove items with updateCart, and attach custom attributes and files.
- [Headless and React](https://docs.sparklayer.io/developers/javascript-sdk/headless.md): Initialise SparkLayer yourself and use it from React.


---

# Options

URL: https://docs.sparklayer.io/developers/javascript-sdk/reference/options

Every window.sparkOptions setting for the SparkLayer Core Script: site and platform, redirects, button selectors, display, translations, checkout and auth.

`window.sparkOptions` configures SparkLayer. It has the type `SparkLayerOptions`, and SparkLayer merges your options with its built-in defaults and the defaults for your `platform`, so you only set what you want to change. `siteId` is the only option you must provide: without it SparkLayer is disabled.

When you add options in your theme, extend the existing object (`window.sparkOptions = { ...window.sparkOptions, … }`) so you don't remove options set by the Core Script or other snippets. See [Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#add-your-own-options-and-hooks).

```typescript
type SparkLayerOptions = {
  sparkDomain: "app.sparklayer.io" | "test.app.sparklayer.io";
  platform: "base" | "bigcommerce" | "shopify" | "wix" | "woocommerce" | "magento";
  siteId: string;
  rootUrl: string;
  accountRedirect: {
    urlRegex?: RegExp;
    goTo?: string;
  };
  cartRedirect: {
    urlRegex?: RegExp;
    goTo?: string;
  };
  wordpressSiteUrl?: string;
  accountButtonSelectors: string;
  logoutButtonSelectors: string;
  cartButtonSelectors: string;
  loginButtonSelectors: string;
  display: DisplayOptions;
  termsAndConditionsLink: string;
  language: string;
  locale: string | null;
  translations: Translations;
  showTranslations: boolean;
  checkoutCustomElements: CheckoutElementConfig[];
  paymentMethodsOrder: PaymentMethodName[];
  saveToAddressBookDefault: boolean;
  productLink: string;
  customAccountDetails: {
    title: string;
    value: string | number;
    displayText?: string;
    type?: CustomAccountDetailLinkType;
  }[];
  onCheckoutValidation(
    cart: Cart,
    cartUiState: CartUIState,
  ): Promise<{ message: string }[] | null>;
  onCartUpdate(cart: Cart, results: CartResults[]): Promise<void>;
  onCartLoad(cart: Cart): Promise<void>;
  preCartUpdateListener(input: Partial<UpdateCart>): Promise<Partial<UpdateCart>>;
  onReady?(spark: Spark): Promise<void>;
  onLoad?(spark: Spark): Promise<void>;
  onLogout?(): Promise<void>;
  shopify?: {
    useAppProxy?: boolean;
  };
  bigcommerce?: {
    appClientId?: string;
  };
  auth: {
    user?: string;
    token?: string;
  };
  authLogoutUri: string | null;
  analytics?: AnalyticsOptions;
  igniteCheckoutContext?: Record<string, unknown>;
};
```

The function-valued options (`onReady`, `onCartUpdate` and the rest) are on the [Hooks](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md) page.

## Site and platform

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `siteId` | `string` | – | Your site ID. Required. |
| `sparkDomain` | `"app.sparklayer.io" \| "test.app.sparklayer.io"` | `"app.sparklayer.io"` | The domain of the SparkLayer API. |
| `platform` | `"base" \| "bigcommerce" \| "shopify" \| "wix" \| "woocommerce" \| "magento"` | `"base"` | Sets the default options for your ecommerce platform. |
| `rootUrl` | `string` | `""` | The root URL used to prefix any URLs SparkLayer creates, generally used for i18n. A trailing `/` is removed. |
| `wordpressSiteUrl?` | `string` | – | The URL of the WordPress site when using the WooCommerce platform. |
| `shopify?` | `{ useAppProxy?: boolean }` | – | Shopify-specific options. |
| `shopify.useAppProxy?` | `boolean` | `true` on Shopify | Send API requests through the Shopify app proxy (`/tools/sparklayer` under `rootUrl`) instead of calling `sparkDomain` directly. |
| `bigcommerce?` | `{ appClientId?: string }` | – | BigCommerce-specific options. |
| `bigcommerce.appClientId?` | `string` | – | Your BigCommerce app client ID. |

## Links and redirects

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `accountRedirect` | `{ urlRegex?: RegExp; goTo?: string }` | – | When a logged-in user visits a path matching `urlRegex`, they're sent to `goTo` with the account drawer open. |
| `accountRedirect.urlRegex?` | `RegExp` | – | Pattern matched against the current path. |
| `accountRedirect.goTo?` | `string` | – | Path (relative to `rootUrl`) to redirect to. |
| `cartRedirect` | `{ urlRegex?: RegExp; goTo?: string }` | – | When a logged-in user visits a path matching `urlRegex`, they're sent to `goTo` with the cart drawer open. |
| `cartRedirect.urlRegex?` | `RegExp` | – | Pattern matched against the current path. |
| `cartRedirect.goTo?` | `string` | – | Path (relative to `rootUrl`) to redirect to. |
| `termsAndConditionsLink` | `string` | `/terms-of-service` (`/policies/terms-of-service` on Shopify) | Link to your terms and conditions. |
| `productLink` | `string` | `/:product-slug:` (`/products/:product-slug:` on Shopify, `/product-page/:product-slug:` on Wix) | The link to a product page, where `:product-slug:` is replaced with the product's slug. |

## Button selectors

SparkLayer attaches to elements matching these CSS selectors. The defaults below are for the `base` platform; BigCommerce, Magento, Shopify, Wix and WooCommerce set their own.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `accountButtonSelectors` | `string` | `[href*="/account"]:not([href$="/account/logout"]), [data-spark-link=account]` | Selectors for the account button. |
| `logoutButtonSelectors` | `string` | `[href$="/account/logout"], [data-spark-link=logout]` | Selectors for the logout button. |
| `cartButtonSelectors` | `string` | `[href$="/cart"], [data-spark-link=cart]` | Selectors for the cart button. |
| `loginButtonSelectors` | `string` | `[href$="/spark-b2b-login"], [data-spark-link=login]` | Selectors for the login button. |

If your site re-renders these buttons, they can lose SparkLayer's click handlers. Open the drawer from your own click handler instead, with [`openDrawer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer).

## Display, language and translations

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `display` | [`DisplayOptions`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#displayoptions) | See [`DisplayOptions`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#displayoptions) | Display options for SparkLayer. |
| `language` | `string` | `"en"` | The language SparkLayer uses. |
| `locale` | `string \| null` | The browser's locale | The locale used for formatting: currently only dates. Examples: `en-GB`, `en-US`, `de-DE`. An empty or unsupported value falls back to the browser locale with a console warning. |
| `translations` | [`Translations`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#translations) | – | Override internal translations, keyed by language code. |
| `showTranslations` | `boolean` | `false` | Shows translation keys instead of text, which helps you debug translations. |

## Checkout and account

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `checkoutCustomElements` | [`CheckoutElementConfig`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#checkoutelementconfig)`[]` | – | Elements to display in checkout: SparkLayer's standard fields (by `id`) or your own custom ones. |
| `paymentMethodsOrder` | [`PaymentMethodName`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#paymentmethodname)`[]` | – | The order in which payment methods are shown. |
| `saveToAddressBookDefault` | `boolean` | `true` | Whether new addresses are saved to the user's address book by default. |
| `customAccountDetails` | `{ title: string; value: string \| number; displayText?: string; type?: CustomAccountDetailLinkType }[]` | – | Title and value pairs to show on a customer's My Details panel. Set `type` (see [`CustomAccountDetailLinkType`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#customaccountdetaillinktype)) to format the value as a link. |
| `igniteCheckoutContext?` | `Record<string, unknown>` | – | A JSON object of checkout context data to pass to Ignite. |

To validate the cart before checkout, use the [`onCheckoutValidation`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncheckoutvalidation) hook.

## Authentication and analytics

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `auth` | `{ user?: string; token?: string }` | – | Credentials for SparkLayer auth. |
| `auth.user?` | `string` | – | The user to authenticate as. |
| `auth.token?` | `string` | – | The token for that user. |
| `authLogoutUri` | `string \| null` | `null` | The logout URI for SparkLayer auth. After logging out, SparkLayer redirects to this path under `rootUrl`. |
| `analytics?` | [`AnalyticsOptions`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#analyticsoptions) | – | Analytics providers and events. See [Event tracking for analytics](https://docs.sparklayer.io/developers/frontend/technical-information.md#event-tracking-for-analytics-google-analytics-ga4). |

## Next steps

- [Set up the SDK](https://docs.sparklayer.io/developers/javascript-sdk/setup.md): Where to set your options so they're in place before the Core Script loads.
- [Hooks](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md): The functions on sparkOptions that SparkLayer calls at key moments.
- [Headless and React](https://docs.sparklayer.io/developers/javascript-sdk/headless.md): Pass these options to window\.initSpark() on a headless storefront.


---

# Hooks

URL: https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks

The SparkLayer SDK hooks, from onReady and onCartUpdate to preCartUpdateListener and onCheckoutValidation: when each runs, what it receives and returns.

Hooks are functions you set on `window.sparkOptions`. SparkLayer calls them at key points so you can run your own code. Each hook returns a promise, so define them as `async` functions. The optional hooks (`onReady`, `onLoad`, `onLogout`) do nothing unless you set them; the others have defaults that do nothing (or, for `preCartUpdateListener`, return the input unchanged).

Set hooks before the Core Script loads. A hook with the same name replaces the earlier one, so keep a reference to any hook that's already set and call it from yours:

```html title="Theme <head>, before the SparkLayer script"
<script>
  (function () {
    var options = (window.sparkOptions = window.sparkOptions || {});
    var previous = options.onCartUpdate;

    options.onCartUpdate = async function (cart, results) {
      if (previous) await previous(cart, results);
      // Your code here
    };
  })();
</script>
```

The examples below use the same pattern. See [Add your own options and hooks](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#add-your-own-options-and-hooks).

| Hook | When it runs |
| --- | --- |
| [`onReady`](#onready) | When SparkLayer has initialised and the page's DOM has loaded. |
| [`onLoad`](#onload) | Once while SparkLayer initialises, before `onReady`. |
| [`onLogout`](#onlogout) | When the user logs out. |
| [`onCartLoad`](#oncartload) | When the cart is loaded. |
| [`onCartUpdate`](#oncartupdate) | Each time the cart is updated. |
| [`preCartUpdateListener`](#precartupdatelistener) | Just before the cart is updated, to change the update. |
| [`onCheckoutValidation`](#oncheckoutvalidation) | Each time the cart loads or changes, to block checkout. |

## onReady()

Called when SparkLayer is ready: after it has initialised and the page's DOM has loaded. It runs whether or not the user is logged in. Start most of your code here.

```typescript title="Signature"
onReady?(spark: Spark): Promise<void>;
```

| Name | Type | Description |
| --- | --- | --- |
| `spark` | [`Spark`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#spark) | The initialised Spark object. |

**Returns:** `Promise<void>`

```javascript title="sparkOptions"
const previousOnReady = window.sparkOptions?.onReady;
window.sparkOptions = {
  ...window.sparkOptions,
  onReady: async (spark) => {
    if (previousOnReady) await previousOnReady(spark);
    if (!(await spark.isLoggedIn())) return;
    // Safe to call spark methods here
  },
};
```

To wait for SparkLayer from a script that may run later, use [`window.sparkReady`](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#wait-for-sparklayer).

## onLoad()

Called once while SparkLayer initialises, after translations have loaded and before `onReady`. It runs whether or not the user is logged in.

```typescript title="Signature"
onLoad?(spark: Spark): Promise<void>;
```

| Name | Type | Description |
| --- | --- | --- |
| `spark` | [`Spark`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#spark) | The Spark object. |

**Returns:** `Promise<void>`

```javascript title="sparkOptions"
const previousOnLoad = window.sparkOptions?.onLoad;
window.sparkOptions = {
  ...window.sparkOptions,
  onLoad: async (spark) => {
    if (previousOnLoad) await previousOnLoad(spark);
    document.documentElement.dataset.sparkPlatform = spark.options.platform;
  },
};
```

## onLogout()

Called when the user logs out. On a headless storefront, use it to log the customer out of your own app too (see [Headless and React](https://docs.sparklayer.io/developers/javascript-sdk/headless.md#load-sparklayer-in-nextjs)).

```typescript title="Signature"
onLogout?(): Promise<void>;
```

**Returns:** `Promise<void>`

```javascript title="sparkOptions"
const previousOnLogout = window.sparkOptions?.onLogout;
window.sparkOptions = {
  ...window.sparkOptions,
  onLogout: async () => {
    if (previousOnLogout) await previousOnLogout();
    sessionStorage.removeItem('b2bCampaign');
  },
};
```

## onCartLoad()

Called when the cart is loaded. Use it to trigger analytics, for example.

```typescript title="Signature"
onCartLoad(cart: Cart): Promise<void>;
```

| Name | Type | Description |
| --- | --- | --- |
| `cart` | [`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart) | The loaded cart. |

**Returns:** `Promise<void>`

```javascript title="sparkOptions"
const previousOnCartLoad = window.sparkOptions?.onCartLoad;
window.sparkOptions = {
  ...window.sparkOptions,
  onCartLoad: async (cart) => {
    if (previousOnCartLoad) await previousOnCartLoad(cart);
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({ event: 'b2b_cart_load', lines: cart.items.length, currency: cart.currencyCode });
  },
};
```

## onCartUpdate()

Called when the cart is updated. Use it to trigger analytics or open the cart drawer, for example.

```typescript title="Signature"
onCartUpdate(cart: Cart, results: CartResults[]): Promise<void>;
```

| Name | Type | Description |
| --- | --- | --- |
| `cart` | [`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart) | The updated cart. |
| `results` | [`CartResults`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cartresults)`[]` | The result of each change in the update. |

**Returns:** `Promise<void>`

```javascript title="sparkOptions"
const previousOnCartUpdate = window.sparkOptions?.onCartUpdate;
window.sparkOptions = {
  ...window.sparkOptions,
  onCartUpdate: async (cart, results) => {
    if (previousOnCartUpdate) await previousOnCartUpdate(cart, results);
    window.spark.openDrawer('cart');
  },
};
```

For more, see [Open the cart drawer](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#open-the-cart-drawer) and [Send cart changes to your analytics](https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics.md#send-cart-changes-to-your-analytics).

## preCartUpdateListener()

Called just before one of SparkLayer's add-to-cart buttons updates the cart. Use it to change the products before the update is sent: for example, to add custom attributes.

```typescript title="Signature"
preCartUpdateListener(input: Partial<UpdateCart>): Promise<Partial<UpdateCart>>;
```

| Name | Type | Description |
| --- | --- | --- |
| `input` | `Partial<`[`UpdateCart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#updatecart)`>` | The cart update about to be sent. It has only the products being added, not the current cart. |

**Returns:** `Promise<Partial<UpdateCart>>`: the cart update to send, changed or not. SparkLayer sends whatever you return.

```javascript title="sparkOptions"
const previousPreCartUpdate = window.sparkOptions?.preCartUpdateListener;
window.sparkOptions = {
  ...window.sparkOptions,
  preCartUpdateListener: async (input) => {
    const update = previousPreCartUpdate ? await previousPreCartUpdate(input) : input;
    const length = document.querySelector('#shirt-length')?.value;
    if (!length || !update.products) return update;
    for (const product of update.products) {
      product.customAttributes = [...(product.customAttributes ?? []), { key: 'Shirt Length', value: length }];
    }
    return update;
  },
};
```

See [Add attributes to SparkLayer's add to cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#add-attributes-to-sparklayers-add-to-cart) for more examples, including files.

## onCheckoutValidation()

Checks whether the user can check out with their current cart. It runs each time the cart loads or changes, and receives the current checkout step, so your rules can vary by step. It must be asynchronous.

```typescript title="Signature"
onCheckoutValidation(
  cart: Cart,
  cartUiState: CartUIState,
): Promise<{ message: string }[] | null>;
```

| Name | Type | Description |
| --- | --- | --- |
| `cart` | [`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart) | The current cart. |
| `cartUiState` | [`CartUIState`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cartuistate) | The current checkout step. |

**Returns:** `Promise<{ message: string }[] | null>`: an array of error objects, or `null` if there are no errors. SparkLayer shows each `message` to the customer.

```javascript title="sparkOptions"
const previousOnCheckoutValidation = window.sparkOptions?.onCheckoutValidation;
window.sparkOptions = {
  ...window.sparkOptions,
  onCheckoutValidation: async (cart, cartUiState) => {
    const errors = (previousOnCheckoutValidation && (await previousOnCheckoutValidation(cart, cartUiState))) || [];
    const samples = cart.items
      .filter((item) => item.sku.startsWith('SAMPLE-'))
      .reduce((total, item) => total + item.quantity, 0);
    if (samples > 3) errors.push({ message: 'You can order up to 3 samples per order.' });
    return errors.length ? errors : null;
  },
};
```

See [Add custom checkout validation](https://docs.sparklayer.io/developers/javascript-sdk/checkout.md#add-custom-checkout-validation).

## Hook error codes

If `onReady`, `onCartLoad` or `onCartUpdate` throws an error when SparkLayer calls it, SparkLayer shows a system error toast with one of these codes and logs the error to the browser console. (SparkLayer doesn't wait for these hooks, so an `async` hook that rejects later shows no code: the browser logs it as an unhandled rejection.)

| Code | Hook that failed |
| --- | --- |
| `OPTIONS:HOOK:OR` | `onReady` |
| `OPTIONS:HOOK:OCL` | `onCartLoad` |
| `OPTIONS:HOOK:OCU` | `onCartUpdate` |

If customers report one of these codes, check that hook in your `sparkOptions` and fix the error shown in the console.

## Next steps

- [Events and analytics](https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics.md): Run your code from hooks and DOM events, and send B2B events to your analytics.
- [Checkout](https://docs.sparklayer.io/developers/javascript-sdk/checkout.md): Block checkout with onCheckoutValidation, including rules chained together.
- [Methods](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md): Every window\.spark method you can call from your hooks.


---

# Methods

URL: https://docs.sparklayer.io/developers/javascript-sdk/reference/methods

Every window.spark method in the SparkLayer SDK, such as getCart, updateCart, getPricingForVariant and fetch, with parameters, return values and examples.

## Wait for SparkLayer

`window.spark` is set as soon as the Core Script runs, but its methods only work once SparkLayer is ready. Call them from the `onReady` hook, or add the [Wait for SparkLayer](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#wait-for-sparklayer) snippet and start with `const spark = await window.sparkReady;`, as the examples on this page do.

## The Spark object

The `Spark` object is available as `window.spark`, and is passed to the [`onReady`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onready) and [`onLoad`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onload) hooks. Its public members are:

```typescript
type Spark = {
  options: SparkLayerOptions;
  isLoggedIn(): Promise<boolean>;
  switchImpersonatingCustomer(customerId: string | null): Promise<UserData | null>;
  refreshGlobalData(): Promise<UserData | null>;
  getActiveCustomerVerificationToken(): Promise<string | null>;
  setActiveCompanySection(sectionId: string): Promise<boolean>;
  getProduct(parentProductId: string): Promise<Product>;
  getProductBySlug(slug: string): Promise<Product>;
  getVariant(parentProductId: string, variantSku: string): Promise<ProductVariant>;
  getPriceForProduct(parentProductId: string): Promise<SimplifiedProductPrice>;
  getPricingForVariant(
    parentProductId: string,
    variantSku: string,
  ): Promise<{
    price: number | null;
    rrp: number | null;
    rrpCurrencyCode: string | null;
    priceBreaks: VariantPriceBreak[];
    currencyCode: string;
  }>;
  getRrpPriceForVariant(
    parentProductId: string,
    variantSku: string,
  ): Promise<{ rrp: number | null; currencyCode: string | null }>;
  getPackSizeForVariant(parentProductId: string, variantSku: string): Promise<number>;
  calculatePricingForVariant(
    parentProductId: string,
    variantSku: string,
    qty: number,
    qtyAcrossVariants?: number | null,
  ): Promise<ProductVariantPricing>;
  calculatePricingForVariantData(
    variant: ProductVariantDataPricing,
    qty: number,
    qtyAcrossVariants?: number | null,
  ): ProductVariantPricing;
  getCart(): Promise<Cart | null>;
  getCartCache(): Cart | null;
  updateCart(
    input: Partial<UpdateCart>,
    cartSuccessHandledLocally?: boolean,
    cartErrorsHandledLocally?: boolean,
  ): Promise<CartResults[] | null>;
  addCustomLineItem(customItem: CustomLineItemInput): Promise<Cart | null>;
  externalClearBasket(): Promise<void>;
  openDrawer(initialTab?: DrawerUIState): void;
  closeDrawer(): void;
  uploadFile(fileName: string, fileData: Blob): Promise<string>;
  fetch<Q extends GraphqlQueryOrMutation<unknown, Record<string, unknown>, GraphqlError | GraphqlExtensionError>>(
    query: Q,
    variables?: VariablesOf<Q>,
    useImpersonatingCustomer?: boolean,
    bypassAppProxy?: boolean,
    signal?: AbortSignal,
  ): Promise<FetchResponse<ResponseOf<Q>, ErrorOf<Q>>>;
};
```

### options

**Type:** [`SparkLayerOptions`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#sparklayeroptions)

The options SparkLayer is running with, after merging your `sparkOptions` with the platform defaults. See [Options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md).

```javascript title="Any script"
const spark = await window.sparkReady;
console.log(spark.options.platform, spark.options.language);
```

## Customers and session

### isLoggedIn()

Checks whether the user is logged in.

```typescript title="Signature"
isLoggedIn(): Promise<boolean>;
```

**Returns:** `Promise<boolean>`

```javascript title="Any script"
const spark = await window.sparkReady;
if (await spark.isLoggedIn()) {
  // Show B2B content
}
```

### switchImpersonatingCustomer()

Switches the customer a sales agent is impersonating, or ends impersonation when you pass `null`.

```typescript title="Signature"
switchImpersonatingCustomer(customerId: string | null): Promise<UserData | null>;
```

| Name | Type | Description |
| --- | --- | --- |
| `customerId` | `string \| null` | The customer to impersonate, or `null` to end impersonation. |

**Returns:** `Promise<`[`UserData`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#userdata)` | null>`

```javascript title="Any script"
const spark = await window.sparkReady;
const customer = await spark.switchImpersonatingCustomer('<CUSTOMER_ID>');
await spark.switchImpersonatingCustomer(null); // End impersonation
```

### refreshGlobalData()

Refetches the current active customer and site configuration, and updates the cached copy both are read from.

```typescript title="Signature"
refreshGlobalData(): Promise<UserData | null>;
```

**Returns:** `Promise<`[`UserData`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#userdata)` | null>`

```javascript title="Any script"
const spark = await window.sparkReady;
const user = await spark.refreshGlobalData();
```

### getActiveCustomerVerificationToken()

Refetches the current active customer and returns a fresh form customer verification token. It uses the impersonated customer when a sales agent is impersonating, otherwise the logged-in customer.

```typescript title="Signature"
getActiveCustomerVerificationToken(): Promise<string | null>;
```

**Returns:** `Promise<string | null>`

```javascript title="Any script"
const spark = await window.sparkReady;
const token = await spark.getActiveCustomerVerificationToken();
```

### setActiveCompanySection()

Selects the company section used for purchasing. If the cart isn't empty, the user is asked to confirm and the cart is cleared. The page then reloads.

```typescript title="Signature"
setActiveCompanySection(sectionId: string): Promise<boolean>;
```

| Name | Type | Description |
| --- | --- | --- |
| `sectionId` | `string` | The ID of one of the logged-in customer's company sections. |

**Returns:** `Promise<boolean>`: `false` if the section isn't available to the customer, the user cancels, or the cart couldn't be cleared.

```javascript title="Any script"
const spark = await window.sparkReady;
const user = await spark.refreshGlobalData();
const section = user?.companySections[0];
if (section) await spark.setActiveCompanySection(section.id);
```

## Products and pricing

Each method takes your platform's parent product ID and, for a variant, its SKU. Prices are for the logged-in customer.

### getProduct()

Fetches the GraphQL product object for a parent product ID.

```typescript title="Signature"
getProduct(parentProductId: string): Promise<Product>;
```

| Name | Type | Description |
| --- | --- | --- |
| `parentProductId` | `string` | The parent product ID. |

**Returns:** `Promise<`[`Product`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#product)`>`

**Throws:** if the product isn't found or an error occurs fetching it.

```javascript title="Any script"
const spark = await window.sparkReady;
const product = await spark.getProduct('6660191387839');
console.log(product.variants.map((variant) => variant.sku));
```

### getProductBySlug()

Fetches the GraphQL product object for a product slug.

```typescript title="Signature"
getProductBySlug(slug: string): Promise<Product>;
```

| Name | Type | Description |
| --- | --- | --- |
| `slug` | `string` | The product slug. |

**Returns:** `Promise<`[`Product`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#product)`>`

**Throws:** if the product isn't found or an error occurs fetching it.

```javascript title="Any script"
const spark = await window.sparkReady;
const product = await spark.getProductBySlug('mother-mug');
```

### getVariant()

Fetches the GraphQL variant object for a parent product ID and variant SKU.

```typescript title="Signature"
getVariant(parentProductId: string, variantSku: string): Promise<ProductVariant>;
```

| Name | Type | Description |
| --- | --- | --- |
| `parentProductId` | `string` | The parent product ID. |
| `variantSku` | `string` | The variant SKU. |

**Returns:** `Promise<`[`ProductVariant`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#productvariant)`>`

**Throws:** if the product or variant isn't found or an error occurs fetching the product.

```javascript title="Any script"
const spark = await window.sparkReady;
const variant = await spark.getVariant('6660191387839', 'MUG-MOM');
console.log(variant.name, variant.stockDisplay?.status);
```

### getPriceForProduct()

Fetches the pricing for a parent product, including price breaks, the lowest price and the number of prices.

```typescript title="Signature"
getPriceForProduct(parentProductId: string): Promise<SimplifiedProductPrice>;
```

| Name | Type | Description |
| --- | --- | --- |
| `parentProductId` | `string` | The parent product ID. |

**Returns:** `Promise<`[`SimplifiedProductPrice`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#simplifiedproductprice)`>`: all price-related data for the parent product, including price breaks, the lowest price and the number of prices. Use the number of prices to decide whether to show "from" before the price.

**Throws:** if the product isn't found or an error occurs fetching it.

```javascript title="Any script"
const spark = await window.sparkReady;
const { fromPrice, numberOfPrices, currencyCode } = await spark.getPriceForProduct('6660191387839');
const label = `${numberOfPrices > 1 ? 'From ' : ''}${fromPrice} ${currencyCode}`;
```

### getPricingForVariant()

Fetches the pricing for a variant.

```typescript title="Signature"
getPricingForVariant(
  parentProductId: string,
  variantSku: string,
): Promise<{
  price: number | null;
  rrp: number | null;
  rrpCurrencyCode: string | null;
  priceBreaks: VariantPriceBreak[];
  currencyCode: string;
}>;
```

| Name | Type | Description |
| --- | --- | --- |
| `parentProductId` | `string` | The parent product ID. |
| `variantSku` | `string` | The variant SKU. |

**Returns:** all price-related data for the variant: `price`, `rrp`, `rrpCurrencyCode`, `priceBreaks` (each a [`VariantPriceBreak`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#variantpricebreak)) and `currencyCode`.

**Throws:** if the product or variant isn't found or an error occurs fetching the product.

```javascript title="Any script"
const spark = await window.sparkReady;
const pricing = await spark.getPricingForVariant('6660191387839', 'MUG-MOM');
console.log(pricing.price, pricing.currencyCode, pricing.priceBreaks);
```

### getRrpPriceForVariant()

Fetches the RRP for a variant.

```typescript title="Signature"
getRrpPriceForVariant(
  parentProductId: string,
  variantSku: string,
): Promise<{ rrp: number | null; currencyCode: string | null }>;
```

| Name | Type | Description |
| --- | --- | --- |
| `parentProductId` | `string` | The parent product ID. |
| `variantSku` | `string` | The variant SKU. |

**Returns:** the RRP (`null` if not set for the currency) and the currency code.

**Throws:** if the product or variant isn't found or an error occurs fetching the product.

```javascript title="Any script"
const spark = await window.sparkReady;
const { rrp, currencyCode } = await spark.getRrpPriceForVariant('6660191387839', 'MUG-MOM');
```

### getPackSizeForVariant()

Fetches the pack size for a variant.

```typescript title="Signature"
getPackSizeForVariant(parentProductId: string, variantSku: string): Promise<number>;
```

| Name | Type | Description |
| --- | --- | --- |
| `parentProductId` | `string` | The parent product ID. |
| `variantSku` | `string` | The variant SKU. |

**Returns:** `Promise<number>`: the variant's pack size, or `1` if none is set.

**Throws:** if the product or variant isn't found or an error occurs fetching the product.

```javascript title="Any script"
const spark = await window.sparkReady;
const packSize = await spark.getPackSizeForVariant('6660191387839', 'MUG-MOM');
const quantity = Math.ceil(10 / packSize) * packSize; // Round 10 up to whole packs
```

### calculatePricingForVariant()

Returns the price for a quantity of a variant, given its parent product ID and SKU.

```typescript title="Signature"
calculatePricingForVariant(
  parentProductId: string,
  variantSku: string,
  qty: number,
  qtyAcrossVariants?: number | null,
): Promise<ProductVariantPricing>;
```

| Name | Type | Description |
| --- | --- | --- |
| `parentProductId` | `string` | The parent product ID. |
| `variantSku` | `string` | The variant SKU. |
| `qty` | `number` | The quantity to calculate pricing for. |
| `qtyAcrossVariants?` | `number \| null` | For tiered pricing, the quantity across variants (if configured). Defaults to `null`. |

**Returns:** `Promise<`[`ProductVariantPricing`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#productvariantpricing)`>`: the total price (quantity × unit price), the unit price and the price breaks.

**Throws:** if the product or variant isn't found or an error occurs fetching the product.

```javascript title="Any script"
const spark = await window.sparkReady;
const pricing = await spark.calculatePricingForVariant('6660191387839', 'MUG-MOM', 2);
console.log(pricing.totalPrice, pricing.unitPrice, pricing.currencyCode);
```

### calculatePricingForVariantData()

Calculates the pricing for a variant from variant data you already have, without fetching.

```typescript title="Signature"
calculatePricingForVariantData(
  variant: ProductVariantDataPricing,
  qty: number,
  qtyAcrossVariants?: number | null,
): ProductVariantPricing;
```

| Name | Type | Description |
| --- | --- | --- |
| `variant` | [`ProductVariantDataPricing`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#productvariantdatapricing) | Variant data, including the RRP and price breaks. A `ProductVariant` or `CartItem` works. |
| `qty` | `number` | The quantity to calculate pricing for. |
| `qtyAcrossVariants?` | `number \| null` | For tiered pricing, the quantity across variants (if configured). Defaults to `null`. |

**Returns:** [`ProductVariantPricing`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#productvariantpricing): the total price (quantity × unit price), the unit price and the price breaks.

```javascript title="Any script"
const spark = await window.sparkReady;
const variant = await spark.getVariant('6660191387839', 'MUG-MOM');
const pricing = spark.calculatePricingForVariantData(variant, 24); // No request
```

See [Live price as the quantity changes](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md#live-price-as-the-quantity-changes) for a full example.

## Cart

See [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md) for worked examples.

### getCart()

Fetches the cart from GraphQL.

```typescript title="Signature"
getCart(): Promise<Cart | null>;
```

**Returns:** `Promise<`[`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart)` | null>`: the cart, or `null` if it couldn't be fetched (an error toast is shown).

```javascript title="Any script"
const spark = await window.sparkReady;
const cart = await spark.getCart();
console.log(cart?.items.length, cart?.totals.total.charge.gross.number);
```

### getCartCache()

Gets the cached cart, if available, without a request.

```typescript title="Signature"
getCartCache(): Cart | null;
```

**Returns:** [`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart)` | null`: the cached cart, or `null` if it isn't available.

```javascript title="Any script"
const spark = await window.sparkReady;
const cart = spark.getCartCache() ?? (await spark.getCart());
```

### updateCart()

Runs an update cart mutation, shows the appropriate toasts and returns the result. It makes every change to the cart: adding, updating and removing items, and setting cart-level fields.

```typescript title="Signature"
updateCart(
  input: Partial<UpdateCart>,
  cartSuccessHandledLocally?: boolean,
  cartErrorsHandledLocally?: boolean,
): Promise<CartResults[] | null>;
```

| Name | Type | Description |
| --- | --- | --- |
| `input` | `Partial<`[`UpdateCart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#updatecart)`>` | Follows the GraphQL `updateCart` mutation's variables. Each product is a [`CartItemInput`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cartiteminput). |
| `cartSuccessHandledLocally?` | `boolean` | Don't show success toasts, as you'll handle the result yourself (useful in the cart, where the update itself shows the change). Defaults to `false`. |
| `cartErrorsHandledLocally?` | `boolean` | Don't show toasts for the messages in the results, as you'll handle them yourself. Defaults to `false`. |

**Returns:** `Promise<`[`CartResults`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cartresults)`[] | null>`: the results, or `null` if the update failed. It doesn't throw: on failure it shows an error toast and logs the error to the console. See [What updateCart returns](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#what-updatecart-returns).

```javascript title="Any script"
const spark = await window.sparkReady;
const results = await spark.updateCart({
  products: [{ sku: 'RED-SHIRT-M', adjustQuantity: 1 }],
});
```

### addCustomLineItem()

Adds a custom line item (a free-text name, price and quantity not tied to a SKU) to the cart. The active customer must have custom cart items enabled, otherwise the request is rejected.

```typescript title="Signature"
addCustomLineItem(customItem: CustomLineItemInput): Promise<Cart | null>;
```

| Name | Type | Description |
| --- | --- | --- |
| `customItem` | [`CustomLineItemInput`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#customlineiteminput) | The name, unit price (as a decimal string) and quantity. |

**Returns:** `Promise<`[`Cart`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#cart)` | null>`: the refreshed cart, or `null` if the item couldn't be added.

```javascript title="Any script"
const spark = await window.sparkReady;
const cart = await spark.addCustomLineItem({ name: 'Artwork set-up', quotedPrice: '25.00', quantity: 1 });
```

### externalClearBasket()

Tells SparkLayer to clear the basket. Designed for your order confirmation (thank you) page.

```typescript title="Signature"
externalClearBasket(): Promise<void>;
```

**Returns:** `Promise<void>`

```javascript title="Order confirmation page"
const spark = await window.sparkReady;
await spark.externalClearBasket();
```

## Drawer

### openDrawer()

Opens the SparkLayer drawer, optionally on a specific tab.

```typescript title="Signature"
openDrawer(initialTab?: DrawerUIState): void;
```

| Name | Type | Description |
| --- | --- | --- |
| `initialTab?` | [`DrawerUIState`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#draweruistate) | The tab to open on. Defaults to `"cart"`. |

**Returns:** `void`

```javascript title="Any script"
const spark = await window.sparkReady;
spark.openDrawer('account');
```

To switch a drawer that's already open to another tab, dispatch the [`view-update`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#view-update) event.

### closeDrawer()

Closes the SparkLayer drawer.

```typescript title="Signature"
closeDrawer(): void;
```

**Returns:** `void`

```javascript title="Any script"
const spark = await window.sparkReady;
spark.closeDrawer();
```

## Files and GraphQL

### uploadFile()

Uploads a file to the SparkLayer file store. Pass the returned ID as a cart item attribute to attach the file (see [Attach a file](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#attach-a-file)).

```typescript title="Signature"
uploadFile(fileName: string, fileData: Blob): Promise<string>;
```

| Name | Type | Description |
| --- | --- | --- |
| `fileName` | `string` | The name of the file, including its extension. It must match the type of the data in `fileData`. |
| `fileData` | `Blob` | The file data as a `Blob`. |

**Returns:** `Promise<string>`: the uploaded file's ID (a GID).

**Throws:** if the file type isn't supported, the file is too large, the file path is invalid, or the upload fails.

```javascript title="Any script"
const spark = await window.sparkReady;
const gid = await spark.uploadFile('design.png', fileBlob);
await spark.updateCart({
  products: [{ sku: 'SHIRT-CUSTOM', adjustQuantity: 1, customAttributes: [{ key: 'Design', value: JSON.stringify([gid]) }] }],
});
```

### fetch()

Runs a GraphQL query or mutation as the authenticated user.

```typescript title="Signature"
fetch<Q>(
  query: Q,
  variables?: VariablesOf<Q>,
  useImpersonatingCustomer?: boolean,
  bypassAppProxy?: boolean,
  signal?: AbortSignal,
): Promise<FetchResponse<ResponseOf<Q>, ErrorOf<Q>>>;
```

**Type parameter:** `Q extends GraphqlQueryOrMutation<unknown, Record<string, unknown>, GraphqlError | GraphqlExtensionError>`. See [`GraphqlQueryOrMutation`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#graphqlqueryormutation).

| Name | Type | Description |
| --- | --- | --- |
| `query` | `Q` | The GraphQL query string. |
| `variables?` | [`VariablesOf<Q>`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#variablesof) | The GraphQL variables. |
| `useImpersonatingCustomer?` | `boolean` | Whether to make the request as the customer being impersonated, rather than as the sales agent. |
| `bypassAppProxy?` | `boolean` | Call the API directly rather than through the platform's app proxy. |
| `signal?` | `AbortSignal` | Aborts the request, for example when its result is no longer needed. |

**Returns:** `Promise<`[`FetchResponse`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#fetchresponse)`<ResponseOf<Q>, ErrorOf<Q>>>`: a standard `Response` object. Check `status`, and call `json()` to get the `data` and `errors`.

```javascript title="Any script"
const spark = await window.sparkReady;
const response = await spark.fetch(`query { loggedInCustomer { id email } }`);
if (response.status === 200) {
  const { data, errors } = await response.json();
  if (!errors?.length) console.log(data.loggedInCustomer.email);
}
```

See [Run a GraphQL query](https://docs.sparklayer.io/developers/javascript-sdk/customers-and-accounts.md#run-a-graphql-query).

## Next steps

- [Types](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md): Cart, Product, UpdateCart and every other type these methods take and return.
- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Add, update and remove items with updateCart, and attach custom attributes and files.
- [Products and pricing](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md): Show trade prices and live quantity pricing in your theme.


---

# Types

URL: https://docs.sparklayer.io/developers/javascript-sdk/reference/types

Every TypeScript type in the SparkLayer JavaScript SDK, from Cart, Product and UpdateCart to SparkLayerOptions and Spark, and where each one is used.

The objects you pass to the SDK and get back from it, written in TypeScript and listed A to Z. In JavaScript, they describe the shape of those objects. Every block on this page goes into [spark.d.ts](https://docs.sparklayer.io/developers/javascript-sdk/spark.d.ts), which you can download for autocomplete and type checking in your editor.

The cart, product and pricing types come from SparkLayer's GraphQL API. Their field types and nullability are inferred from how the SDK uses them, so treat a field as possibly `null` unless you're sure it's set.

## AccountSectionId

The sections of the My Account panel, used in [`display.sectionConfiguration`](#displayoptions) to reorder or hide them.

```typescript
type AccountSectionId =
  | "spark-slot-my-account"
  | "recent-activity"
  | "shopping-lists"
  | "favourites"
  | "financials"
  | "my-details"
  | "reports"
  | "address-book"
  | "company-users";
```

**Used by:** [`DisplayOptions`](#displayoptions)

## AnalyticsEventName

The B2B events SparkLayer can send to your analytics. See [Event tracking for analytics](https://docs.sparklayer.io/developers/frontend/technical-information.md#event-tracking-for-analytics-google-analytics-ga4) for what each event means.

```typescript
type AnalyticsEventName =
  | "addToCart"
  | "cartUpdate"
  | "shoppingListSave"
  | "shoppingListLoad"
  | "shoppingListDelete"
  | "csvUpload"
  | "quickAdd"
  | "finalStageCheckout"
  | "shippingUpdate"
  | "beginCheckout"
  | "purchase"
  | "viewCart";
```

**Used by:** [`AnalyticsOptions`](#analyticsoptions)

## AnalyticsOptions

The type of the `analytics` option: the providers to send events to, and which events each one gets. See [Event tracking for analytics](https://docs.sparklayer.io/developers/frontend/technical-information.md#event-tracking-for-analytics-google-analytics-ga4).

```typescript
type AnalyticsOptions = {
  providers: {
    // "ga" for Google Analytics (GA4), "gtm" for Google Tag Manager, or your own function
    handler: "ga" | "gtm" | ((eventName: AnalyticsEventName, eventParams: unknown) => void);
    // The events to send to this provider
    events: Partial<Record<AnalyticsEventName, boolean>>;
  }[];
};
```

**Used by:** the [`analytics`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#authentication-and-analytics) option

## Cart

The B2B cart.

```typescript
type Cart = {
  cartUuid: string;
  intent: string; // For example "ORDER"
  canCreateOrder: boolean;
  canCreateQuote: boolean;
  hasLaunched: boolean;
  lockedByUserId: string | null;
  lockedByUserLastAccessedAt: string | null;
  loadedFromPurchaseAt: string | null;
  loadedFromPurchaseType: string | null;
  items: CartItem[];
  validationErrors: CartValidationError[];
  taxInclusiveDisplay: boolean;
  totals: CartTotals;
  currencyCode: string;
  totalWeight: number | null;
  customerAddresses: { id: string; description: string }[];
  deliveryAddressId: string | null;
  customerReference: string | null;
  poNumber: string | null;
  shippingRequestedDate: string | null;
  customFields: { name: string; value: string }[];
  approvingFor: { name: string } | null;
  discounts: {
    id: string;
    slug: string;
    name: string;
    appliedCouponCodes: string[];
    amount: { net: number; gross: number; currencyCode: string };
  }[];
  discountsAreAvailable: boolean;
  couponCodes: string[];
  removedCouponCodes: string[];
  quote: {
    statusSlug: string;
    statusUpdated: string;
    expiry: string | null;
    assignedAgent: { id: string } | null;
    message: string | null;
    note: string | null;
  } | null;
};
```

**Used by:** [`getCart()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getcart), [`getCartCache()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getcartcache), [`addCustomLineItem()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#addcustomlineitem), [`onCartLoad`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncartload), [`onCartUpdate`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncartupdate), [`onCheckoutValidation`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncheckoutvalidation)

## CartItem

One line in the cart. It has every [`ProductVariant`](#productvariant) field (`sku`, `name`, `price` and so on) plus these:

```typescript
type CartItem = ProductVariant & {
  type: string;
  itemKey: string; // Identifies the line in updateCart
  quantity: number;
  customAttributes: { key: string; value: string; type?: string | null }[];
  lineTotal: CartLineAmount;
  lineTotalPreDiscounts: CartLineAmount;
  lineTotalDiscountAmount: CartLineAmount;
  unitTotal: CartLineAmount;
  unitTotalPreDiscounts: CartLineAmount;
  unitTotalDiscountAmount: CartLineAmount;
  quotedPrice: string | null;
  preorderQuantityDisplay: number | null;
};
```

**Used by:** [`Cart`](#cart) (`items`), [`calculatePricingForVariantData()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariantdata)

## CartItemInput

One product in an [`UpdateCart`](#updatecart). Identify the line by `sku` or `itemKey`, and set the quantity with `adjustQuantity` (added to the current quantity; negative to remove) or `quantity` (the exact quantity; `0` removes the line).

```typescript
type CartItemInput = {
  sku?: string;
  itemKey?: string; // From a CartItem
  adjustQuantity?: number;
  quantity?: number;
  customAttributes?: { key: string; value: string; type?: string }[];
};
```

For a file, `value` is a JSON string of an array of file GIDs from [`uploadFile()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#uploadfile).

**Used by:** [`UpdateCart`](#updatecart) (`products`)

## CartLineAmount

An amount on a cart line, such as its total or unit price.

```typescript
type CartLineAmount = {
  net: number;
  gross: number;
  currencyCode: string;
  taxInclusiveDisplay: boolean;
};
```

**Used by:** [`CartItem`](#cartitem)

## CartMoney

An amount in the cart's totals.

```typescript
type CartMoney = { number: string };
```

**Used by:** [`CartTotals`](#carttotals)

## CartResults

The result for one product line in an `updateCart` call. See [What updateCart returns](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#what-updatecart-returns) for the `messages` types.

```typescript
type CartResults = {
  messages: { type: string }[];
  requestedQuantity: number;
  resultantQuantity: number;
  itemKey: string;
  sku: string;
  name: string;
};
```

**Used by:** [`updateCart()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#updatecart), [`onCartUpdate`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncartupdate)

## CartTotals

The cart's totals. Each amount is a [`CartMoney`](#cartmoney) object with a `number`.

```typescript
type CartTotals = {
  subTotal: {
    preDiscount: { net: CartMoney; gross: CartMoney };
    discount: { net: CartMoney; gross: CartMoney };
    charge: { net: CartMoney; gross: CartMoney };
  };
  shipping: {
    preDiscount: { net: CartMoney };
    discount: { net: CartMoney };
    charge: { net: CartMoney };
  };
  total: {
    charge: { gross: CartMoney; tax: CartMoney };
    discount: { net: CartMoney };
    preDiscount: { gross: CartMoney };
  };
};
```

**Used by:** [`Cart`](#cart) (`totals`)

## CartUIState

The current checkout step.

```typescript
type CartUIState = "cart" | "shipping" | "quote-details" | "payment" | "thanks";
```

**Used by:** [`onCheckoutValidation`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#oncheckoutvalidation)

## CartValidationError

A reason the cart can't be checked out yet, such as an order minimum that hasn't been met. Each error has a `type` code (for example `quantity-unavailable` or `pricing-unavailable`) and the fields for its kind.

The `type` is one of the cart validation codes the API uses: `maximum-order-item-quantity`, `maximum-order-totals`, `maximum-parent-quantity`, `maximum-variant-quantity`, `minimum-order-item-quantity`, `minimum-order-totals`, `minimum-parent-quantity`, `minimum-variant-quantity`, `pack-size`, `pricing-unavailable`, `pricing-unavailable-for-selected-qty` or `quantity-unavailable`.

```typescript
type CartValidationError = {
  type: string;
  amount?: number;
  amountGross?: number;
  minimum?: number;
  maximum?: number;
  productName?: string;
  parentSKU?: string;
  variantSKU?: string;
  packSize?: number;
  availableQuantity?: number;
  overridden?: boolean;
};
```

| Kind of error (GraphQL type) | Fields |
| --- | --- |
| `CartValidationErrorMinimumOrderTotals`, `CartValidationErrorMaximumOrderTotals` | `amount`, `amountGross` |
| `CartValidationErrorMinimumOrderItemQuantity` | `minimum` |
| `CartValidationErrorMaximumOrderItemQuantity` | `maximum` |
| `CartValidationErrorMinimumParentQuantity`, `CartValidationErrorMaximumParentQuantity` | `minimum` or `maximum`, `productName`, `parentSKU`, `overridden` |
| `CartValidationErrorMinimumVariantQuantity`, `CartValidationErrorMaximumVariantQuantity` | `minimum` or `maximum`, `variantSKU`, `overridden` |
| `CartValidationErrorPackSize` | `packSize`, `variantSKU`, `overridden` |
| `CartValidationErrorQuantityUnavailable` | `variantSKU`, `availableQuantity` |
| `CartValidationErrorPricingUnavailable`, `CartValidationErrorPricingUnavailableForSelectedQty` | `variantSKU` |

**Used by:** [`Cart`](#cart) (`validationErrors`)

## CheckoutElementConfig

One entry in `checkoutCustomElements`: a standard field by `id`, or a custom field by `name`. See [Custom field settings](https://docs.sparklayer.io/help/ordering/checkout-fields.md#custom-field-settings) for every key and [Standard checkout fields](https://docs.sparklayer.io/help/ordering/checkout-fields.md#turn-on-standard-checkout-fields) for the IDs.

```typescript
type CheckoutElementConfig = {
  // A standard field
  id?: "customer-reference" | "po-number" | "shipping-requested-date";
  // A custom field (required unless id is set)
  name?: string;
  // Customer-facing text, keyed by language code
  translations?: Record<string, { title: string; detail?: string; [messageKey: string]: string | undefined }>;
  // HTML attributes such as type, required, min, max, maxlength and pattern
  attributes?: Record<string, string | number | boolean>;
  // For select fields: the drop-down options, optionally in groups
  options?: {
    translations?: Record<string, { groupName: string }>;
    items: { value: string; translations: Record<string, { label: string }> }[];
  }[];
  // Returns a message key from translations if the value is invalid
  onChange?(value: string, element: HTMLElement): string | null | undefined;
};
```

**Used by:** the [`checkoutCustomElements`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) option

## CustomAccountDetailLinkType

Formats a `customAccountDetails` value as a link of this kind.

```typescript
type CustomAccountDetailLinkType = "email" | "phone" | "sms" | "website";
```

**Used by:** the [`customAccountDetails`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) option

## CustomLineItemInput

A custom line item: a free-text name, price and quantity not tied to a SKU.

```typescript
type CustomLineItemInput = {
  // The name shown on the custom line item
  name: string;
  // The price of a single unit, as a decimal string
  quotedPrice: string;
  quantity: number;
};
```

**Used by:** [`addCustomLineItem()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#addcustomlineitem)

## DisplayOptions

The type of the `display` option.

```typescript
type DisplayOptions = {
  orderListShowShippingAddress: boolean;
  customerReferenceHidden: boolean; // deprecated
  customerReferenceRequired: boolean; // deprecated
  customerReferenceMaxLength?: number; // deprecated
  darkTheme: boolean;
  savingsUseRrp: boolean;
  roundPriceBreakPercentages: boolean;
  showPriceBreakSavings: boolean;
  sectionConfiguration: {
    "my-account"?: {
      order?: AccountSectionId[];
      hide?: AccountSectionId[];
    };
  };
  showSlots: string[];
  showRrpToggle: boolean;
  showFavouritesLists: boolean;
  showShoppingLists: boolean;
  showSkus: boolean;
  hideFinancials?: boolean;
};
```

| Property | Default | What it does |
| --- | --- | --- |
| `sectionConfiguration` | `{}` | Reorder (`order`) or hide (`hide`) My Account sections by [`AccountSectionId`](#accountsectionid). See [My account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md). |
| `showSlots` | `[]` | Custom slots to show. See [Custom slots](https://docs.sparklayer.io/help/storefront/interfaces/custom-slots.md). |
| `showFavouritesLists` | `true` | Whether to show the favourites lists feature. |
| `showShoppingLists` | `true` | Whether to show the shopping lists feature. |
| `showSkus` | `true` | Whether to show product SKUs on cart line items. |
| `darkTheme` | `false` | Use the dark theme. See [Customising design](https://docs.sparklayer.io/help/storefront/customising-design.md). |
| `savingsUseRrp` | `false` | Calculate savings against the RRP. |
| `roundPriceBreakPercentages` | `true` | Round price break percentages. |
| `showPriceBreakSavings` | `true` | Show savings on price breaks. |
| `showRrpToggle` | `false` | Show the RRP toggle. |
| `orderListShowShippingAddress` | `false` | Show the shipping address in the purchases list. |
| `hideFinancials?` | – | Hide the Financials section of My Account. |
| `customerReferenceHidden`, `customerReferenceRequired`, `customerReferenceMaxLength?` | `false`, `false`, – | Deprecated. Use a `{ id: 'customer-reference' }` entry in `checkoutCustomElements` instead. |

**Used by:** the [`display`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#display-language-and-translations) option

## DrawerUIState

A tab of the SparkLayer drawer.

```typescript
type DrawerUIState = "dashboard" | "browse-catalog" | "cart" | "sales-agent" | "account";
```

**Used by:** [`openDrawer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer), the [`view-update`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#view-update) event

## ErrorOf

The error type of a GraphQL query or mutation passed to `fetch`. For a plain query string, it's [`GraphqlError`](#graphqlerror).

```typescript
type ErrorOf<Q> = Q extends { readonly __graphqlTypes?: { error: infer TError } }
  ? TError
  : GraphqlError;
```

**Used by:** [`fetch()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch)

## FetchResponse

The response returned by `fetch`: a standard `Response` whose `json()` resolves to the GraphQL response.

```typescript
interface FetchResponse<TData = unknown, TError = GraphqlError> extends Response {
  json(): Promise<{ data: TData; errors: TError[] }>;
}
```

**Used by:** [`fetch()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch)

## GraphqlError

An entry in the `errors` array of a GraphQL response.

```typescript
type GraphqlError = {
  message: string;
  path?: (string | number)[];
  extensions?: { code?: string; [key: string]: unknown };
};
```

**Used by:** [`FetchResponse`](#fetchresponse), [`fetch()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch)

## GraphqlExtensionError

A [`GraphqlError`](#graphqlerror) with a `code` in `extensions` that identifies the error.

```typescript
type GraphqlExtensionError = GraphqlError & {
  extensions: { code: string; [key: string]: unknown };
};
```

**Used by:** [`fetch()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch)

## GraphqlQueryOrMutation

The query you pass to `fetch`. In JavaScript, pass it as a string, and the variables as a plain object. In TypeScript, a typed query can also carry its response, variables and error types, which [`ResponseOf`](#responseof), [`VariablesOf`](#variablesof) and [`ErrorOf`](#errorof) read back.

```typescript
type GraphqlQueryOrMutation<
  TResponse = unknown,
  TVariables = Record<string, unknown>,
  TError = GraphqlError,
> = string & {
  // Type-only: never set at runtime
  readonly __graphqlTypes?: { response: TResponse; variables: TVariables; error: TError };
};
```

**Used by:** [`fetch()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch)

## PaymentMethodName

The payment methods you can list in `paymentMethodsOrder`.

```typescript
type PaymentMethodName = "paymentOnAccount" | "paymentByInvoice" | "upfrontPayment" | "quote";
```

**Used by:** the [`paymentMethodsOrder`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#checkout-and-account) option

## Product

A product, with its variants.

```typescript
type Product = {
  id: string;
  externalId: string; // Your platform's product ID
  slug: string;
  variants: ProductVariant[];
};
```

**Used by:** [`getProduct()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getproduct), [`getProductBySlug()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getproductbyslug), the [`spark-variant-change`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#spark-variant-change) event

## ProductVariant

One variant of a product, and the base of each [`CartItem`](#cartitem).

```typescript
type ProductVariant = {
  id: string;
  externalId: string; // Your platform's variant ID
  parentExternalId: string; // Your platform's product ID
  stockDisplay: {
    status: string; // For example "out_of_stock" or "backorder"
    units: number | null;
    available: unknown;
  } | null;
  restockDate: string | null;
  cartImageUrl: string | null;
  position: number;
  sku: string;
  barcode: string | null;
  slug: string;
  name: string;
  price: VariantPrice | null;
  rrp: unknown; // Legacy: use rrpV2
  rrpV2: { number: string; currency: string } | null;
  priceBreaks: VariantPriceBreak[];
  // Product settings, such as packSize, minOrderQuantity and maxOrderQuantity
  settings: { key: string; value: unknown }[];
  // The variant's options, such as { group: "Size", value: "M" }
  options: { group: string; value: string }[];
};
```

**Used by:** [`getVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getvariant), [`Product`](#product) (`variants`), [`CartItem`](#cartitem), [`calculatePricingForVariantData()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariantdata), the [`spark-variant-change`](https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components.md#spark-variant-change) event

## ProductVariantDataPricing

The variant data `calculatePricingForVariantData` needs. A [`ProductVariant`](#productvariant) or [`CartItem`](#cartitem) has these fields.

```typescript
type ProductVariantDataPricing = {
  priceBreaks: VariantPriceBreak[] | null;
  rrpV2?: { number: string; currency: string } | null;
  unitTotal?: { currencyCode: string } | null; // Cart items only
};
```

**Used by:** [`calculatePricingForVariantData()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariantdata)

## ProductVariantPricing

The price for a quantity of a variant: the total, the unit price at that quantity and the price breaks.

```typescript
type ProductVariantPricing = {
  totalPrice: number | null; // unitPrice × quantity
  totalRrpPrice: number | null;
  hasPriceBreaks: boolean;
  unitPrice: number | null; // The unit price at this quantity
  basePrice: number | null; // The unit price before price breaks
  priceBreaks: VariantPriceBreak[];
  priceBreakSavingsPercentage: number | null;
  rrpV2: { number: string; currency: string } | null;
  currencyCode: string;
  unitPriceBreakdown: {
    items: {
      unitOfMeasure: string | null;
      price: number;
      quantity: number;
      uomQuantity: number;
    }[];
  };
};
```

**Used by:** [`calculatePricingForVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariant), [`calculatePricingForVariantData()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#calculatepricingforvariantdata)

## ResponseOf

The `data` type of a GraphQL query or mutation passed to `fetch`. For a plain query string, it's `unknown`.

```typescript
type ResponseOf<Q> = Q extends { readonly __graphqlTypes?: { response: infer TResponse } }
  ? TResponse
  : unknown;
```

**Used by:** [`fetch()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch)

## SimplifiedProductPrice

The "from" price across a product's variants, and how many different prices there are.

```typescript
type SimplifiedProductPrice = {
  numberOfPrices: number;
  numberOfPricesExcludingBreaks: number;
  numberOfRrpPrices: number;
  fromPrice: number | null;
  fromPriceExcludingBreaks: number | null;
  currencyCode: string;
  hasPriceBreaks: boolean;
  rrpPrice: number | null;
  rrpCurrencyCode: string | null;
  taxInclusiveDisplay: boolean;
};
```

If `numberOfPrices` is more than 1, show "from" before `fromPrice`.

**Used by:** [`getPriceForProduct()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpriceforproduct)

## Spark

The `window.spark` object. See [Methods](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md) for each one.

```typescript
type Spark = {
  options: SparkLayerOptions;
  isLoggedIn(): Promise<boolean>;
  switchImpersonatingCustomer(customerId: string | null): Promise<UserData | null>;
  refreshGlobalData(): Promise<UserData | null>;
  getActiveCustomerVerificationToken(): Promise<string | null>;
  setActiveCompanySection(sectionId: string): Promise<boolean>;
  getProduct(parentProductId: string): Promise<Product>;
  getProductBySlug(slug: string): Promise<Product>;
  getVariant(parentProductId: string, variantSku: string): Promise<ProductVariant>;
  getPriceForProduct(parentProductId: string): Promise<SimplifiedProductPrice>;
  getPricingForVariant(
    parentProductId: string,
    variantSku: string,
  ): Promise<{
    price: number | null;
    rrp: number | null;
    rrpCurrencyCode: string | null;
    priceBreaks: VariantPriceBreak[];
    currencyCode: string;
  }>;
  getRrpPriceForVariant(
    parentProductId: string,
    variantSku: string,
  ): Promise<{ rrp: number | null; currencyCode: string | null }>;
  getPackSizeForVariant(parentProductId: string, variantSku: string): Promise<number>;
  calculatePricingForVariant(
    parentProductId: string,
    variantSku: string,
    qty: number,
    qtyAcrossVariants?: number | null,
  ): Promise<ProductVariantPricing>;
  calculatePricingForVariantData(
    variant: ProductVariantDataPricing,
    qty: number,
    qtyAcrossVariants?: number | null,
  ): ProductVariantPricing;
  getCart(): Promise<Cart | null>;
  getCartCache(): Cart | null;
  updateCart(
    input: Partial<UpdateCart>,
    cartSuccessHandledLocally?: boolean,
    cartErrorsHandledLocally?: boolean,
  ): Promise<CartResults[] | null>;
  addCustomLineItem(customItem: CustomLineItemInput): Promise<Cart | null>;
  externalClearBasket(): Promise<void>;
  openDrawer(initialTab?: DrawerUIState): void;
  closeDrawer(): void;
  uploadFile(fileName: string, fileData: Blob): Promise<string>;
  fetch<Q extends GraphqlQueryOrMutation<unknown, Record<string, unknown>, GraphqlError | GraphqlExtensionError>>(
    query: Q,
    variables?: VariablesOf<Q>,
    useImpersonatingCustomer?: boolean,
    bypassAppProxy?: boolean,
    signal?: AbortSignal,
  ): Promise<FetchResponse<ResponseOf<Q>, ErrorOf<Q>>>;
};
```

**Used by:** `window.spark`, [`window.initSpark()`](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#manual-initialisation-headless-only), [`onReady`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onready), [`onLoad`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#onload)

## SparkLayerOptions

The type of `window.sparkOptions` and the options you pass to `window.initSpark()`. See [Options](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md) and [Hooks](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md) for each one.

```typescript
type SparkLayerOptions = {
  sparkDomain: "app.sparklayer.io" | "test.app.sparklayer.io";
  platform: "base" | "bigcommerce" | "shopify" | "wix" | "woocommerce" | "magento";
  siteId: string;
  rootUrl: string;
  accountRedirect: {
    urlRegex?: RegExp;
    goTo?: string;
  };
  cartRedirect: {
    urlRegex?: RegExp;
    goTo?: string;
  };
  wordpressSiteUrl?: string;
  accountButtonSelectors: string;
  logoutButtonSelectors: string;
  cartButtonSelectors: string;
  loginButtonSelectors: string;
  display: DisplayOptions;
  termsAndConditionsLink: string;
  language: string;
  locale: string | null;
  translations: Translations;
  showTranslations: boolean;
  checkoutCustomElements: CheckoutElementConfig[];
  paymentMethodsOrder: PaymentMethodName[];
  saveToAddressBookDefault: boolean;
  productLink: string;
  customAccountDetails: {
    title: string;
    value: string | number;
    displayText?: string;
    type?: CustomAccountDetailLinkType;
  }[];
  onCheckoutValidation(
    cart: Cart,
    cartUiState: CartUIState,
  ): Promise<{ message: string }[] | null>;
  onCartUpdate(cart: Cart, results: CartResults[]): Promise<void>;
  onCartLoad(cart: Cart): Promise<void>;
  preCartUpdateListener(input: Partial<UpdateCart>): Promise<Partial<UpdateCart>>;
  onReady?(spark: Spark): Promise<void>;
  onLoad?(spark: Spark): Promise<void>;
  onLogout?(): Promise<void>;
  shopify?: {
    useAppProxy?: boolean;
  };
  bigcommerce?: {
    appClientId?: string;
  };
  auth: {
    user?: string;
    token?: string;
  };
  authLogoutUri: string | null;
  analytics?: AnalyticsOptions;
  igniteCheckoutContext?: Record<string, unknown>;
};
```

**Used by:** `window.sparkOptions`, [`window.initSpark()`](https://docs.sparklayer.io/developers/javascript-sdk/setup.md#manual-initialisation-headless-only), [`Spark`](#spark) (`options`)

## Translations

The type of the `translations` option: text overrides keyed by language code, then by translation key. See [Change text in the Core Script](https://docs.sparklayer.io/help/storefront/languages-and-international.md#change-text-in-the-core-script).

```typescript
type Translations = Record<string, Record<string, string>>;
```

**Used by:** the [`translations`](https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md#display-language-and-translations) option

## UpdateCart

A change to the cart. Every field is optional: send only what you want to change. See [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md).

```typescript
type UpdateCart = {
  clearCart?: boolean;
  products?: CartItemInput[];
  deliveryAddressId?: string;
  customerReference?: string;
  poNumber?: string;
  shippingRequestedDate?: string;
  customFields?: { name: string; value: string }[];
  cartIntent?: string;
};
```

SparkLayer adds the impersonated customer and company section for you.

**Used by:** [`updateCart()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#updatecart), [`preCartUpdateListener`](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md#precartupdatelistener)

## UserData

The active customer. This lists the fields most integrations need; the object has more.

```typescript
type UserData = {
  id: string;
  email: string;
  name: string;
  companyName: string | null;
  customerVerificationToken: string | null;
  salesAgent: boolean;
  parentAccount: { id: string; name: string; email: string } | null;
  companySections: { id: string; name: string }[];
};
```

**Used by:** [`switchImpersonatingCustomer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#switchimpersonatingcustomer), [`refreshGlobalData()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#refreshglobaldata)

## VariablesOf

The variables type of a GraphQL query or mutation passed to `fetch`. For a plain query string, it's any plain object.

```typescript
type VariablesOf<Q> = Q extends { readonly __graphqlTypes?: { variables: infer TVariables } }
  ? TVariables
  : Record<string, unknown>;
```

**Used by:** [`fetch()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#fetch)

## VariantPrice

A variant's price for the customer.

```typescript
type VariantPrice = {
  taxRate: number;
  net: number;
  gross: number;
  currencyCode: string;
  taxInclusiveDisplay: boolean; // If true, show gross; otherwise net
};
```

**Used by:** [`ProductVariant`](#productvariant) (`price`), [`VariantPriceBreak`](#variantpricebreak)

## VariantPriceBreak

One price break (tier) for a variant: the price per unit from `quantity` upwards.

```typescript
type VariantPriceBreak = {
  quantity: number;
  price: VariantPrice;
  unitOfMeasure: string | null;
};
```

**Used by:** [`getPricingForVariant()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#getpricingforvariant), [`ProductVariant`](#productvariant), [`ProductVariantPricing`](#productvariantpricing)

## Next steps

- [Methods](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md): Every window\.spark method, with the types it takes and returns.
- [Hooks](https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md): The functions SparkLayer calls with a Cart, CartResults or the Spark object.
- [Cart](https://docs.sparklayer.io/developers/javascript-sdk/cart.md): Build an UpdateCart and handle the CartResults it returns.


---

# Events and components

URL: https://docs.sparklayer.io/developers/javascript-sdk/reference/events-and-components

SparkLayer's web components, such as spark-pdp and spark-product-card, and the DOM events they dispatch, with each event.detail and an example of each.

SparkLayer's interfaces are web components: custom HTML elements you add to your theme. Some of them dispatch DOM events you can listen for, and you can dispatch one yourself to switch the drawer's tab.

## DOM events

| Event | When it fires | `event.detail` | Bubbles? |
| --- | --- | --- | --- |
| [`spark-variant-change`](#spark-variant-change) | The customer selects a variant in `spark-pdp` or `spark-product-card`. Dispatched on that element. | `{ product: Product; variant: ProductVariant }` | No: listen on each element. |
| [`spark-file-attachment-changed`](#spark-file-attachment-changed) | The list of files uploaded to a `spark-file-upload-field` changes. | `{ fileSize: number; fileName: string; gid: string }[] \| null` (`null` when every file is removed) | Yes, to `window`. |
| [`spark-file-attachment-failed`](#spark-file-attachment-failed) | A file fails to upload to a `spark-file-upload-field`. | `{ fileSize: number; fileName: string; errorCode: "unsupported-file-type" \| "file-too-large" \| "default" }` | Yes, to `window`. |
| [`view-update`](#view-update) | You dispatch it on `window` to switch an open drawer to a tab. | `{ view: DrawerUIState }` | You dispatch it with `bubbles: true`. |

### spark-variant-change

`event.detail.product` is a [`Product`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#product) and `event.detail.variant` a [`ProductVariant`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#productvariant); their `externalId` is your platform's ID. Add the listeners in `onReady`, once the elements are on the page.

```javascript title="sparkOptions"
window.sparkOptions = {
  ...window.sparkOptions,
  onReady: async () => {
    for (const card of document.querySelectorAll('spark-product-card')) {
      card.addEventListener('spark-variant-change', (event) => {
        console.log(event.detail.product.externalId, event.detail.variant.externalId);
      });
    }
  },
};
```

See [Update the product image when a variant is selected](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md#update-the-product-image-when-a-variant-is-selected).

### spark-file-attachment-changed

```javascript title="Product page"
window.addEventListener('spark-file-attachment-changed', (event) => {
  const gids = (event.detail ?? []).map((file) => file.gid);
  document.querySelector('#shirt-design').value = JSON.stringify(gids);
});
```

See [Let customers upload a file](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#let-customers-upload-a-file) to attach the files to the cart.

### spark-file-attachment-failed

```javascript title="Product page"
window.addEventListener('spark-file-attachment-failed', (event) => {
  const { fileName, errorCode } = event.detail;
  console.warn(`${fileName} wasn't uploaded: ${errorCode}`);
});
```

### view-update

`view` is a [`DrawerUIState`](https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md#draweruistate). To open a closed drawer, use [`openDrawer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer).

```javascript title="Switch the open drawer to the Cart tab"
window.dispatchEvent(
  new CustomEvent('view-update', {
    bubbles: true,
    composed: true,
    detail: { view: 'cart' },
  }),
);
```

See [Open the cart drawer](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#open-the-cart-drawer).

## Web components

`parent-id` is your platform's ID for the parent product. For each interface's display settings (attributes such as `show-sku`), see [How products are shown](https://docs.sparklayer.io/help/storefront/product-display.md).

| Element | What it renders | Key attributes | See |
| --- | --- | --- | --- |
| `<spark-pdp>` | The product detail interface, on product pages. | `parent-id` | [Product detail](https://docs.sparklayer.io/help/storefront/interfaces/product-detail.md) |
| `<spark-product-card>` | The product card interface, wherever a product card appears. | `parent-id` | [Product card](https://docs.sparklayer.io/help/storefront/interfaces/product-card.md) |
| `<spark-product-matrix>` | Every variant in a grid, for products with two options. | `parent-id` | [Product matrix](https://docs.sparklayer.io/help/storefront/interfaces/product-matrix.md) |
| `<spark-product-price>` | The customer's price for a product, anywhere on the page. | `parent-id` | [Product price](https://docs.sparklayer.io/help/storefront/interfaces/product-price.md) |
| `<spark-product-rrp>` | The product's RRP. | `parent-id` | [Product price](https://docs.sparklayer.io/help/storefront/interfaces/product-price.md) |
| `<spark-file-upload-field>` | A file upload field for the product page. | `allowed-extensions` (a JSON array), `max-file-size` (bytes), `max-files`, `required` | [Let customers upload a file](https://docs.sparklayer.io/developers/javascript-sdk/cart.md#let-customers-upload-a-file) |
| `<spark-drawer>` | The drawer (cart, account and other tabs). SparkLayer adds it when needed; use [`openDrawer()`](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer) rather than adding it yourself. | – | [openDrawer()](https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md#opendrawer) |

```html title="Product page"
<spark-pdp parent-id="{{ product.id }}"></spark-pdp>

<spark-file-upload-field
  id="shirt-design-upload"
  allowed-extensions='["png", "jpg", "jpeg"]'
  max-files="1"
></spark-file-upload-field>
```

## Next steps

- [Events and analytics](https://docs.sparklayer.io/developers/javascript-sdk/events-and-analytics.md): Run your code from hooks and DOM events, and send B2B events to your analytics.
- [Products and pricing](https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md): Swap the product image when a customer selects a variant.
- [Frontend integration](https://docs.sparklayer.io/developers/frontend.md): Add the product page interfaces and hide elements from B2B customers.


---

# Templates

URL: https://docs.sparklayer.io/developers/templates

Build custom SparkLayer invoice, quote and email templates in Liquid, using the currency, translate, ldate and country filters, sections and language files.

Templates set the design and wording of the PDFs and emails SparkLayer creates, such as invoices, quotes and purchase approval emails. They're written in [Liquid](https://shopify.github.io/liquid/), and each one receives the data listed under [Available data](#available-data).

## The templates

| Template | Type | What it's for |
| --- | --- | --- |
| invoice.liquid | PDF | The invoice |
| quote.liquid | PDF | The quote |
| limited-user-purchase-review\.liquid | Email | Sent when a [limited user](https://docs.sparklayer.io/help/glossary.md#limited-user) places a purchase that needs approving |
| limited-user-purchase-approve.liquid | Email | Sent when a limited user's purchase is approved |
| new-quote-notification-to-merchant.liquid | Email | Tells you a customer has asked for a quote |
| quote-assigned-notification-to-agent.liquid | Email | Tells a sales agent a quote has been assigned to them |
| purchase-history-message-notification-to-agent.liquid | Email | Tells a sales agent about a new message on an order or quote |
| purchase-history-message-notification-to-customer.liquid | Email | Tells a customer about a new message on an order or quote |
| email-header.liquid | Section | The header every email shares |
| email-footer.liquid | Section | The footer every email shares |

Only the templates above can be used. Any other files uploaded to a theme are discarded, including supporting files such as images and fonts.

### Create and upload a template

1. In the SparkLayer Dashboard, go to **Settings > Templates** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/theme)), or **SparkLayer Wholesale > Settings > Templates** in the Shopify app.
2. Click **Create template**. SparkLayer creates a template theme for you to edit.
3. Add only the files you'll change, and edit them in the SparkLayer editor. Click **Save** to create a revision. To go back, open a previous revision from the **Revisions** drop-down and save it.
4. For bigger changes, download the template as a ZIP file, work on it with your own tools, then zip it up and upload it.

A new template is empty, so it falls back to SparkLayer's core templates and language files until you add files to it. Once you add a file, it's no longer updated from the core templates: if a new feature changes a core template, copy the change into your file. See [Templates](https://docs.sparklayer.io/help/dashboard/settings.md#templates) in the Help Center for more. 

### Template markup and Liquid

Templates are written in [Liquid](https://shopify.github.io/liquid/) and have access to most Liquid tags and filters, plus the helper filters below.

Add styling in the template, in a `style` element or inline styles. All styles are inlined when the template is rendered, for better compatibility with email clients.

The email templates are tested in modern web-based email clients such as Gmail. Older email clients, such as desktop versions of Outlook, aren't supported. Test your custom email templates, because email clients often handle modern HTML and CSS badly.

### Filters and blocks

- [Currency](#currency)
- [Translate](#translate)
- [Localised date format](#localised-date-format)
- [Country from country code](#country-from-country-code)
- [Template sections](#template-sections)

### Currency

Use the `currency` filter for monetary values. It renders the currency with the right formatting for the locale.

```liquid title="Template"
{{ "9.99" | currency: "gbp" }}
```

```text title="Output"
£9.99
```

To change the currency formatting, pass one of these options:

- `display_none`
- `display_code`
- `display_symbol` (default)

```liquid title="Template"
{{ "9.99" | currency: "gbp", "display_code" }}
```

```text title="Output"
GBP 9.99
```

The filter also has a shorthand alias, `c`, which works the same way.

### Translate

Use the `translate` filter to translate text in a template. The theme needs a language file with the translation strings. See [Internationalisation and translations](#internationalisation-and-translations) for how to add language files.

```json title="en.json"
{
  "example": {
    "heading": "Welcome to SparkLayer!"
  }
}
```

```liquid title="Template"
{{ "example.heading" | translate }}
```

```text title="Output"
Welcome to SparkLayer!
```

The filter also has a shorthand alias, `t`, which works the same way.

To insert values into a string, add numbered slots to the string and pass the values as arguments to the filter:

```json title="en.json"
{
  "example": {
    "heading": "Dear ${1} of ${2}"
  }
}
```

```liquid title="Template"
{{ "example.heading" | translate: "Jeremy Sparks", "SparkLayer" }}
```

```text title="Output"
Dear Jeremy Sparks of SparkLayer
```

This filter translates using the store locale from the merchant data (`data.merchant`), falling back on the `en` translation file if no translation is found for the respective locale.

### Localised date format

Use the `ldate` filter to format dates for a locale. By default, it uses the store's locale from the merchant data (`data.merchant`). To use another locale, pass it as a parameter.

```liquid title="Template"
{{ "2024-10-22T16:18:02.196Z" | ldate }}
```

```text title="Output"
22/10/2024
```

With a locale:

```liquid title="Template"
{{ "2024-10-22T16:18:02.196Z" | ldate: "fr-CA" }}
```

```text title="Output"
2024-10-22
```

### Country from country code

Use the `country` filter to show a country name from its country code. This helps with address data, which stores the country code rather than the name.

```liquid title="Template"
{{ "gb" | country }}
```

```text title="Output"
United Kingdom
```

Country names are always returned in English, whatever the store's locale.

### Template sections

Use the `section` tag to include a section template. Only the section templates listed under [The templates](#the-templates) are supported; you can't add custom sections.

```liquid title="Template"
<main>
    {% section email-header %}
    <p>Content</p>
    {% section email-footer %}
</main>
```

```html title="Output"
<main>
    <header>
        <h1>Hello World</h1>
    </header>
    <p>Content</p>
    <footer>Copyright Year</footer>
</main>
```

## Internationalisation and translations

You can add language JSON files to a theme to translate its templates. Name each file with a language code (such as `en` or `fr`) that matches the locale used by your store. The translations in these files are available through the [translate](#translate) Liquid filter.

By default, the filter uses the store's locale. If your language files have no translation for a key, it falls back to SparkLayer's core language files, with `en` as the final fallback.

## Available data

Templates get their data through the `data` Liquid variable, for example `data.merchant.store_name`.

| Template | Top-level objects |
| --- | --- |
| invoice.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase), [settings](https://docs.sparklayer.io/developers/templates/template-objects.md#invoicesettings) |
| quote.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase) |
| limited-user-purchase-review\.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase) |
| limited-user-purchase-approve.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase) |
| new-quote-notification-to-merchant.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase) |
| quote-assigned-notification-to-agent.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase), [assignment\_details](https://docs.sparklayer.io/developers/templates/template-objects.md#assignmentdetails) |
| purchase-history-message-notification-to-agent.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase), [purchase\_history\_message](https://docs.sparklayer.io/developers/templates/template-objects.md#purchasehistorymessage) |
| purchase-history-message-notification-to-customer.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase), [purchase\_history\_message](https://docs.sparklayer.io/developers/templates/template-objects.md#purchasehistorymessage) |
| email-header.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant) |
| email-footer.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant) |

The data varies by template, but every template has the store details (`data.merchant`). [This object](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant) holds the store's general information, which you can change in the [SparkLayer Dashboard settings](https://docs.sparklayer.io/help/dashboard/settings.md).

## Next steps

- [Template objects](https://docs.sparklayer.io/developers/templates/template-objects.md): every object and property available to templates.
- [Templates in the Help Center](https://docs.sparklayer.io/help/dashboard/settings.md#templates): what merchants can change with templates.
- [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md): the languages SparkLayer supports.


---

# Template objects

URL: https://docs.sparklayer.io/developers/templates/template-objects

Properties of the objects available in SparkLayer Liquid templates, including Merchant, Purchase, LineItem, Customer, Address, Money and invoice content zones.

These are the SparkLayer objects you can use in [templates](https://docs.sparklayer.io/developers/templates.md) and invoice content zones. Which objects are available depends on the template: check the template's documentation to see what it receives.

Nested properties are shown with dot notation (for example `dates.created_at`), and `[]` marks an array item.

## Address

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `name` | `string` | The addressee's name | _-_ |
| `company` | `string` | The company name | _-_ |
| `address_line1` | `string` | Line 1 of the address | _-_ |
| `address_line2` | `string,null` | Line 2 of the address | _-_ |
| `city` | `string` | The city | _-_ |
| `region_code` | `string,null` | The region code, such as a state or county code | _-_ |
| `postal_code` | `string,null` | The postal code or postcode | _-_ |
| `country_code` | `string` | The country code. Use the [`country` filter](https://docs.sparklayer.io/developers/templates.md#country-from-country-code) to show the country name | _-_ |
| `phone` | `string,null` | The phone number | _-_ |

## Customer

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `id` | `string` | The customer's SparkLayer ID | _-_ |
| `title` | `string` | The customer's title | _-_ |
| `first_name` | `string` | The customer's first name | _-_ |
| `last_name` | `string` | The customer's last name | _-_ |
| `email` | `string` | The customer's email address | _-_ |
| `company_name` | `string,null` | The customer's company name | _-_ |
| `external_id` | `string` | - | _-_ |
| `accounting_id` | `string` | - | _-_ |

## ContentZone

Content zones are configured as part of the invoicing feature. They can contain Liquid variables, so handle them accordingly in your templates.

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `title` | `string,null` | The content zone's title | _-_ |
| `content` | `string,null` | The content zone's content, which can contain Liquid variables | _-_ |

## InvoiceSettings

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `content_zones.zone_1` | [ContentZone](#contentzone) | Invoice content zone 1 | _-_ |
| `content_zones.zone_2` | [ContentZone](#contentzone) | Invoice content zone 2 | _-_ |
| `content_zones.zone_3` | [ContentZone](#contentzone) | Invoice content zone 3 | _-_ |

## LineItem

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `custom_attributes.[].key` | `string` | A custom attribute's key | _-_ |
| `custom_attributes.[].value` | `string` | A custom attribute's value | _-_ |
| `identifiers.sku` | `string,null` | The product's SKU | _-_ |
| `name_child` | `string,null` | - | _-_ |
| `name_parent` | `string` | - | _-_ |
| `quantity` | `integer` | The quantity ordered | _-_ |
| `line_total` | [LineTotal](#linetotal) or `null` | The totals for the whole line | _-_ |
| `unit_total` | [UnitTotal](#unittotal) or `null` | The totals for one unit | _-_ |
| `image_url` | `string,null` | The URL of the product's image | _-_ |
| `product_slug` | `string,null` | - | _-_ |
| `rrp` | [Money](#money) or `null` | The recommended retail price (RRP) | _-_ |
| `barcode` | `string,null` | The product's barcode | _-_ |

## LineTotal

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `total_net` | [Money](#money) | The line total, excluding tax | _-_ |
| `discount_net` | [Money](#money) | The discount on the line, excluding tax | _-_ |
| `tax_rate` | `number` | The tax rate applied to the line | _-_ |

## Merchant

The merchant's store details.

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `address1` | `string,null` | Line 1 of the merchant's store address | _-_ |
| `address2` | `string,null` | Line 2 of the merchant's store address | _-_ |
| `base_currency` | `string,null` | The base currency used by the store | _USD,GBP_ |
| `city` | `string,null` | City of the merchant's store address | _-_ |
| `region` | `string,null` | Region code of the merchant's store address | _-_ |
| `country` | `string,null` | Country code of the merchant's store address | _GB_ |
| `email` | `string,null` | The merchant's email address | _-_ |
| `phone` | `string,null` | The merchant's store phone number | _-_ |
| `postcode` | `string,null` | Postcode of the merchant's store address | _-_ |
| `store_name` | `string,null` | The connected platform's store name | _-_ |
| `timezone` | `string,null` | The store's time zone | _-_ |
| `url` | `string,null` | The store's URL | _-_ |
| `locale` | `string,null` | The default locale of the store | _en,fr_ |

## Money

A monetary value.

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `amount` | `string` | The amount | _-_ |
| `currency` | `string` | The currency code | _GBP,USD_ |

## Package

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `line_items` | `array of` [LineItem](#lineitem) | The line items in the package | _-_ |
| `shipping_address` | [Address](#address) | The address the package is shipped to | _-_ |

## Purchase

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `currency_code` | `string` | The purchase's currency code | _-_ |
| `billing_address` | [Address](#address) | The billing address | _-_ |
| `customers.sparklayer` | [Customer](#customer) | The SparkLayer customer who placed the purchase | _-_ |
| `custom_fields.[].name` | `string` | A custom field's name | _-_ |
| `custom_fields.[].value` | `string,null` | A custom field's value | _-_ |
| `customer_reference` | `string,null` | The customer's own reference for the purchase | _-_ |
| `dates.created_at` | `string` | When the purchase was created | _-_ |
| `dates.updated_at` | `string` | When the purchase was last updated | _-_ |
| `dates.placed_at` | `string,null` | When the purchase was placed | _-_ |
| `dates.calculated_submitted_at` | `string,null` | - | _-_ |
| `identifiers.visible` | `string` | The purchase ID shown to customers | _-_ |
| `packages` | `array of` [Package](#package) | The purchase's packages, each with its line items and shipping address | _-_ |
| `line_items` | `array of` [LineItem](#lineitem) | The purchase's line items | _-_ |
| `subtotal` | [Money](#money) | The subtotal | _-_ |
| `tax` | [Money](#money) | The total tax | _-_ |
| `shipping_cost` | [Money](#money) | The shipping cost | _-_ |
| `calculated_total` | [Money](#money) | The calculated total | _-_ |
| `tax_lines` | `array of` [TaxLine](#taxline) | The tax lines that make up the total tax | _-_ |

## UnitTotal

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `total_net` | [Money](#money) | The unit price, excluding tax | _-_ |
| `total_gross` | [Money](#money) | The unit price, including tax | _-_ |
| `total_tax` | [Money](#money) | The tax on one unit | _-_ |
| `tax_rate` | `number` | The tax rate applied | _-_ |

## TaxLine

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `title` | `string` | The tax line's name | _-_ |
| `rate` | `number` | The tax rate | _-_ |
| `amount.number` | `string` | The tax amount | _-_ |
| `amount.currency` | `string` | The tax amount's currency code | _-_ |

## PurchaseHistoryMessage

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `body` | `string` | The message's text | _-_ |
| `created_at` | `string` | When the message was sent | _-_ |
| `customer` | [Customer](#customer) | The customer who sent the message | _-_ |

## AssignmentDetails

### Properties

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| `assigned_by` | [Customer](#customer) | Who assigned the quote | _-_ |
| `assigned_on` | `string` | When the quote was assigned | _-_ |

If a property doesn't behave as described here, [contact our support team](https://docs.sparklayer.io/help/support.md).

## Next steps

- [Templates](https://docs.sparklayer.io/developers/templates.md): the templates you can customise and the filters they can use.
- [Invoices](https://docs.sparklayer.io/help/ordering/invoices.md): the invoice PDF and its settings.


---

# Data and limits

URL: https://docs.sparklayer.io/developers/data

Reference for how SparkLayer stores extra product, customer and order data in metafields, and the recommended and hard limits on the data you send.

SparkLayer keeps some settings, such as a product's pack size or a customer's price lists, in [metafields](https://docs.sparklayer.io/help/glossary.md#metafields): extra fields on products, customers and orders in your eCommerce platform. Use these pages to look up the keys SparkLayer reads, and the limits to design your integration around.

- [Metafields](https://docs.sparklayer.io/developers/data/metafields.md): Every SparkLayer product, customer and order metafield key and type, such as `pack_size`, `rrp`, `price_lists` and `payment_on_account`, and how to auto-configure them.
- [Data limitations](https://docs.sparklayer.io/developers/data/data-limitations.md): Recommended and hard limits for SparkLayer data, including products, customers, customer groups, price lists, cart line items, addresses and discounts.


---

# Metafields

URL: https://docs.sparklayer.io/developers/data/metafields

Every SparkLayer product, customer and order metafield key and type, such as pack_size, rrp, price_lists and payment_on_account, and how to auto-configure them.

Metafields store extra information that your eCommerce platform doesn't usually capture. SparkLayer uses them for additional B2B data:

| Type | Used for |
| --- | --- |
| **Product metafields** | Configuring the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md), such as [pack sizes](https://docs.sparklayer.io/help/storefront/quantity-rules.md) and [RRP prices](https://docs.sparklayer.io/help/pricing/pricing-display.md) |
| **Customer metafields** | Adding customer information, such as [credit limits](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) |
| **Order metafields** | Adding [invoicing information](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) to an order, and importing order history |

This page lists every metafield SparkLayer supports. On Shopify, each one uses the namespace `sparklayer`, for example `sparklayer.pack_size`. For setting them up on your platform, see:

- [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md)
- [BigCommerce metafields and data mapping](https://docs.sparklayer.io/help/platforms/bigcommerce/metafields.md)

## Automatically configure metafields

On Shopify, SparkLayer can create its metafield definitions for you.

1. In the [SparkLayer Dashboard](https://app.sparklayer.io/configuration/integrations/platform), go to **Integrations > Platform connection**.
2. In the **Configure metafields** section, click **Configure**. You'll see every metafield that can be configured for **Product** and **Customer** data.

Each metafield you enable is added to [Custom data](https://admin.shopify.com/settings/custom_data) in your Shopify admin and pinned, so it's easy to find when you edit products or customers.

![SparkLayer metafields pinned in Shopify's custom data settings](https://docs.sparklayer.io/images/shared/metafields-66d501.webp)

Metafields created this way are named `B2B - [name]`, for example `B2B - Pack Size`. To change or remove them, use [Custom data](https://admin.shopify.com/settings/custom_data) in your Shopify admin.

## Product metafields

Apply all product metafields at the variant level.

| Metafield | Key | Type |
| --- | --- | --- |
| **Recommended retail price (RRP).** Sets an RRP ("MSRP") price for a variant. See [pricing display](https://docs.sparklayer.io/help/pricing/pricing-display.md). | `rrp` | `json` |
| **Pack size.** Sets pack size rules for products, such as 6, 12 or 18. See [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md). | `pack_size` | `integer` |
| **Minimum purchasable quantity (variant level).** The minimum quantity of the variant customers must buy. See [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md). | `min_order_quantity` | `integer` |
| **Maximum purchasable quantity (variant level).** The maximum quantity of the variant customers can buy. See [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md). | `max_order_quantity` | `integer` |
| **Minimum purchasable quantity (product level).** The minimum quantity customers must buy across all variants. See [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md). | `min_order_parent_quantity` | `integer` |
| **Maximum purchasable quantity (product level).** The maximum quantity customers can buy across all variants. See [quantity rules](https://docs.sparklayer.io/help/storefront/quantity-rules.md). | `max_order_parent_quantity` | `integer` |
| **Reserve stock.** Reserves an amount of stock that isn't available for regular purchase, for example to hold inventory for specific customers, events or direct-to-consumer sales. See [stock display](https://docs.sparklayer.io/help/storefront/stock-display.md). | `reserve_stock_quantity` | `integer` |
| **Product visibility.** Whether a variant is visible on the storefront. If disabled, customers don't see the variant, even if it can still be bought in other ways. See [product display](https://docs.sparklayer.io/help/storefront/product-display.md). | `display` | `boolean` |
| **Purchasing.** Whether a variant can be added to the cart and bought. When disabled, the product stays visible but can't be bought, for example to showcase upcoming or unavailable items. See [product display](https://docs.sparklayer.io/help/storefront/product-display.md). | `sell` | `boolean` |
| **Customer group product rules.** B2B product rules, such as pack size and orderable quantities, for specific customer groups. Overrides the metafields above. See [product settings](https://docs.sparklayer.io/help/storefront/product-settings.md). | `settings` | `json` |
| **Reserved DTC stock quantity.** A stock quantity to reserve for your direct-to-consumer (DTC) customers. See [stock display](https://docs.sparklayer.io/help/storefront/stock-display.md). | `min_stock_level` | `integer` |
| **Restock date.** The date a product in pre-order status is expected to be available. See [stock display](https://docs.sparklayer.io/help/storefront/stock-display.md). | `restock_date` | `date` |
| **Stock location settings.** B2B stock settings, such as minimum stock level and restock date, for specific stock locations. See [stock display](https://docs.sparklayer.io/help/storefront/stock-display.md). | `stock_location_data` | `json` |

You can also set customer-specific product rules: see [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md).

## Customer metafields

| Metafield | Key | Type |
| --- | --- | --- |
| **Customer title.** The customer's title (such as Mr, Ms or Dr), for personalising invoices, emails and account records. See [account and addresses](https://docs.sparklayer.io/help/customers/account-and-addresses.md). | `title` | `single line text` |
| **Company name.** The name of the customer's company. See [account and addresses](https://docs.sparklayer.io/help/customers/account-and-addresses.md). | `company_name` | `single line text` |
| **Assigned group.** The customer group assigned to the customer. Overrides any tags assigned to the customer. | `group` | `single line text` |
| **Customer-specific price lists.** The price lists assigned to the customer. Overrides any price lists assigned to the customer group. See [customer pricing](https://docs.sparklayer.io/help/pricing/customer-pricing.md). | `price_lists` | `json`<br />`single_line_text` |
| **Invoice payment.** JSON settings that define whether the customer can pay by invoice, so approved customers can complete purchases without paying straight away. See [credit, net terms and invoicing](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md). | `payment_by_invoice` | `json` |
| **Credit limit and account balance.** The customer's credit limit and account balance. See [credit, net terms and invoicing](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md). | `payment_on_account` | `json` |
| **Accounting ID.** A unique accounting ID for the customer. See [account and addresses](https://docs.sparklayer.io/help/customers/account-and-addresses.md). | `accounting_id` | `single line text` |
| **Additional percentage discount.** A flat discount percentage applied on top of other discounted pricing. See [customer pricing](https://docs.sparklayer.io/help/pricing/customer-pricing.md). | `discount_percentage` | `single line text`<br />`integer`<br />`float` |
| **Sales agent groups.** The sales agent groups assigned to the customer, so dedicated representatives can manage the account. See [restricting which customers a sales agent can see](https://docs.sparklayer.io/help/sales-reps.md#restrict-which-customers-a-sales-agent-can-see). | `sales_agent_groups` | `list.single_line_text` |
| **Parent account.** Links the customer to a parent customer account, for businesses with multi-level accounts, sub-customers and centralised purchasing. See [company users](https://docs.sparklayer.io/help/customers/company-users.md). | `parent_customer_id` | `single line text` |
| **Customer role.** The customer's role in their company, used to apply permissions. See [company users](https://docs.sparklayer.io/help/customers/company-users.md). | `role` | `single line text` |
| **Default shipping address ID.** The shipping address to use by default for orders. See [account and addresses](https://docs.sparklayer.io/help/customers/account-and-addresses.md). | `shipping_address_id` | `single line text` |
| **Default billing address ID.** The billing address to use by default for orders. See [account and addresses](https://docs.sparklayer.io/help/customers/account-and-addresses.md). | `billing_address_id` | `single line text` |
| **Available shipping addresses.** JSON listing every shipping address available to the customer, for businesses with several delivery locations. See [account and addresses](https://docs.sparklayer.io/help/customers/account-and-addresses.md). | `available_shipping_address_ids` | `json` |

To use the advanced metafields, [speak to our team](https://docs.sparklayer.io/help/support.md) about how they work.

## Order metafields

| Metafield | Key | Type |
| --- | --- | --- |
| **Invoice link.** A URL to the order's invoice, so customers can get to digital invoices quickly. See [credit, net terms and invoicing](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md). | `invoice_url` | `url`<br />`list.url`<br />`file_reference`<br />`list.file_reference` |
| **Order import.** Set to `true` to import a historic order into SparkLayer, so customers see it in their order history. See [importing order history](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#import-order-history-into-sparklayer). | `order_import` | `boolean` |
| **Visible ID.** A custom order ID shown instead of the platform's order number, for example your ERP order number, so the ID is the same in every system. Shopify only. See [setting a custom order number](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#set-a-custom-order-number). | `visible_id` | `single line text` |

## Next steps

- [Shopify metafields and data mapping](https://docs.sparklayer.io/help/platforms/shopify/metafields.md): set up and fill in metafields on Shopify.
- [Data limitations](https://docs.sparklayer.io/developers/data/data-limitations.md): limits on the data you send to SparkLayer.
- [Building integrations](https://docs.sparklayer.io/developers/building-integrations.md): how data flows between SparkLayer and your other systems.


---

# Data limitations

URL: https://docs.sparklayer.io/developers/data/data-limitations

Recommended and hard limits for SparkLayer data, including products, customers, customer groups, price lists, cart line items, addresses and discounts.

SparkLayer is built to scale, but there are limits on how much data it can process without affecting performance. They matter most if you have large data sets, such as a high volume of price lists.

| Area | Recommended maximum | Hard limit (performance implications) |
| --- | --- | --- |
| **Customer groups** | 50 | 100 |
| **Products** | 50,000 | 100,000 |
| **Customers** | 100,000 | 250,000 |
| **Customer sub-accounts**\* | 250 | 250 |
| **Customer addresses**\* | 250 | 500 |
| **Sales agents** | Not applicable | None |
| **Sales agent groups** | 1,000 | 2,500 |
| **Price lists** | 15,000 | 25,000 |
| **Customer carts** | Unlimited (stored for up to 3 months after the last change) | |
| **Line items in a cart** | 250 | 250 |
| **Discounts** | 50 unique discounts, 15 concurrent | 100 unique discounts, 25 concurrent |

\*Limit per customer

## Platform limitations

For limitations specific to a platform, see [Integrations](https://docs.sparklayer.io/help/integrations.md).

## Next steps

- [Metafields](https://docs.sparklayer.io/developers/data/metafields.md): the extra product, customer and order data SparkLayer stores.
- [Architecture](https://docs.sparklayer.io/developers/architecture.md): how SparkLayer connects to your other systems.


---

# 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.

**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.


---

# Platform connection

URL: https://docs.sparklayer.io/ignite/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.

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 removed. A new connection can start from the eCommerce platform or from the SparkLayer Dashboard, and your integration needs to support both flows.

## Platform connection flows

### Initiated through the eCommerce platform

The merchant starts the connection from the platform's app store (or similar), for example by installing the SparkLayer app on BigCommerce or Shopify. This flow only applies if your platform supports third-party apps.

This flow uses the **SparkLayer Dashboard API** to register the user with SparkLayer, create a platform connection between the platform and a SparkLayer site, and get the site's onboarding progress. Its documentation isn't public, but we can provide it on request.

1. The merchant installs the SparkLayer app on their store.
2. Your integration stores the store's credentials and other data it needs, usually the store identifier and the platform's API access token or credentials.
3. The SparkLayer app on the platform shows the user a SparkLayer registration page. To register the user, call the Dashboard API's user registration endpoint.
4. When registration succeeds, SparkLayer returns the site environment and Site ID. Use them to call the Dashboard API's site platform connection endpoint, which links the store to the new SparkLayer site.
5. SparkLayer calls your integration's [Connect a platform](https://docs.sparklayer.io/ignite/api/new-platform-connection.md) endpoint with the Site ID and credentials. Store them and run the connection completion actions, such as a full data sync.
6. The connection is complete. In the platform's SparkLayer app, show the user the SparkLayer onboarding steps, with links to the SparkLayer Dashboard and the Help Center. Get the onboarding progress from the Dashboard API's onboarding steps endpoint.

### Initiated through the SparkLayer Dashboard

The merchant starts the connection from the eCommerce platform page of an existing SparkLayer site in the SparkLayer Dashboard (**Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app). 

1. SparkLayer calls your integration's [Connect a platform](https://docs.sparklayer.io/ignite/api/new-platform-connection.md) endpoint with the SparkLayer site and credentials.
2. Your integration stores this data and returns a `redirect_url`, where the merchant installs the SparkLayer app on the platform.
3. Once the app is installed, your integration stores the store's credentials and other data it needs.
4. Your integration now has both the SparkLayer and the platform data, so the connection is complete and it can start actions such as a full data sync.
5. Show the user the SparkLayer onboarding steps and progress, from the Dashboard API's onboarding steps endpoint.

## Platform connection endpoints

SparkLayer calls these endpoints to tell your integration about a new or removed platform connection.

### New platform connection

[Connect a platform](https://docs.sparklayer.io/ignite/api/new-platform-connection.md) (`POST /v1/{siteEnv}/{siteId}`) records the new connection, and runs the completion actions if the connection is complete.

The request body includes:

| Field | Description |
| --- | --- |
| `store_id` | The store's ID on the platform |
| `spark_api_client_id` and `spark_api_client_secret` | API credentials your integration uses to call the [SparkLayer API](https://docs.sparklayer.io/developers/api.md) for this site |
| `extra_config`, `magento_*` | Platform-specific credentials for WooCommerce and Magento |

Respond with:

- `201` and a `redirect_url` when the connection is pending: the SparkLayer Dashboard redirects the merchant there to install the SparkLayer app on the platform
- `204` when the app is already installed and the connection is now active

Once the connection is complete (your integration has the SparkLayer and platform configuration and credentials, and can start syncing data):

1. Register any data change webhooks with the platform, if it has them.
2. Sync the store settings from the platform to the SparkLayer API.
3. Start a full sync of customers and products.

**Important considerations:**

- The connection may not be complete when SparkLayer calls this endpoint: for example, when the connection starts in the SparkLayer Dashboard and the merchant still has to finish it on the platform. In that case, return a `redirect_url` to the platform's SparkLayer installation page, where the merchant links their store to the pending connection.
- The endpoint must be idempotent, because SparkLayer may call it more than once. If the connection is already established, re-trigger the completion actions safely.

### Remove platform connection

[Disconnect a platform](https://docs.sparklayer.io/ignite/api/remove-platform-connection.md) (`DELETE /v1/{siteEnv}/{siteId}`) should:

- Stop processing any syncs
- [Delete the store's sync logs](https://docs.sparklayer.io/developers/api/sync-log/delete-a-stores-sync-logs.md)
- Delete the connection data stored by your integration

## Authentication between SparkLayer and your integration

**Calls from your integration to SparkLayer.** Use the `spark_api_client_id` and `spark_api_client_secret` from the connect request to get OAuth access tokens, as described in [Authentication](https://docs.sparklayer.io/developers/authentication.md). Tokens are short-lived, so store them with the connection data and refresh them when they expire.

**Calls from SparkLayer to your integration.** The Ignite spec lists `401 Auth Failure` responses for these endpoints, but doesn't define how SparkLayer authenticates its requests. 

## Next steps

- [Authentication](https://docs.sparklayer.io/ignite/authentication.md): verify customers signed in to your platform.
- [Data sync](https://docs.sparklayer.io/ignite/data-sync.md): the full sync to run once the connection is complete.


---

# Ignite authentication

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

How Ignite verifies platform customer sessions: SparkLayer passes a token such as a BigCommerce JWT to /authentication/verify and issues an access token.

When a customer signs in to their account on the eCommerce platform, SparkLayer needs to authenticate them too. To avoid making customers sign in twice (to the platform and to SparkLayer), some platforms let third parties such as SparkLayer authenticate a signed-in customer. These mechanisms differ between platforms, so Ignite defines one generic endpoint, [Verify storefront authentication](https://docs.sparklayer.io/ignite/api/verify-authentication.md), that receives the authentication data to verify.

This diagram shows how the authentication data moves from the storefront to your Ignite integration.

Ignite authentication sequence:

1. Front end → SparkLayer API: `POST /api/v1/ignite/authentication/verify`
2. SparkLayer API → Ignite API: `POST /authentication/verify`
3. The Ignite API verifies the authentication data.
4. Ignite API → SparkLayer API: the customer ID.
5. The SparkLayer API generates an access token for that customer ID.
6. SparkLayer API → front end: the access token.

## What your integration does

SparkLayer sends `POST /v1/{siteEnv}/{siteId}/authentication/verify` with the authentication data in the `data` property of the request body.

1. Verify the data, using whatever mechanism your platform provides.
2. Work out which customer it belongs to: it must be possible to derive the customer's platform ID from the data.
3. Respond with `200` and the customer's platform ID in `customer.external_id`. If the data can't be verified, respond with an error.

SparkLayer then uses the customer ID you return to generate an access token for that customer, and returns it to the customer's browser. The browser uses this access token for every later request to the SparkLayer API.

## BigCommerce example

When a B2B customer has signed in to a BigCommerce store:

1. SparkLayer's JavaScript in the customer's browser calls BigCommerce's [current customer endpoint](https://developer.bigcommerce.com/docs/storefront-auth/current-customer#get-current-customer), which returns a JSON Web Token (JWT).
2. The browser passes the JWT to SparkLayer's API.
3. SparkLayer passes the JWT to the Ignite service for BigCommerce at `/v1/{siteEnv}/{siteId}/authentication/verify`. Delegating verification keeps platform-specific code out of SparkLayer's core API.
4. The Ignite service verifies the token and returns the customer's BigCommerce ID.
5. SparkLayer generates an access token for that customer and returns it to the browser.

## Next steps

- [Data sync](https://docs.sparklayer.io/ignite/data-sync.md): sync products, customers, orders and settings to SparkLayer.
- [Verify storefront authentication](https://docs.sparklayer.io/ignite/api/verify-authentication.md): the endpoint's full request and response.


---

# Ignite data sync

URL: https://docs.sparklayer.io/ignite/data-sync

Sync products, pricing, customers, orders and store settings from your platform to SparkLayer with full syncs, webhook-driven updates and the sync-log API.

Data sync brings data from your platform, such as an eCommerce platform, into SparkLayer. Merchants see the data in the [SparkLayer Dashboard](https://docs.sparklayer.io/help/dashboard.md), and the [SparkLayer Frontend](https://docs.sparklayer.io/help/storefront.md) uses it to power the wholesale ordering experience: which customers SparkLayer is enabled for, what pricing they see, and their order history.

## When data sync happens

A full data sync runs:

- When the app is installed
- When data is inconsistent and needs refreshing. SparkLayer calls your integration's [Trigger a data sync](https://docs.sparklayer.io/ignite/api/trigger-a-data-sync.md) endpoint when someone clicks the manual sync buttons for products and customers in the SparkLayer Dashboard. This is only available to internal staff, such as SparkLayer support.

After that, partial updates keep data in sync, driven by webhooks or other events from the eCommerce platform.

### Important considerations

| Area | Notes |
| --- | --- |
| Queueing and retry | Retry partial sync events if they fail, so the platform stays stable and reliable. |
| Performance | Design the service so heavy use of our API doesn't affect it, and make as few updates as possible. For example, for a product update, fetch the product and its stock levels and only update what's changed. |
| Reporting | Log the last updated date and the last full sync with the [Sync Logging API](https://docs.sparklayer.io/developers/api/sync-log.md), as described in [Logging sync issues](#logging-sync-issues). |
| Issue logging | Handle any issues during the sync and log them with the Sync Logging API, so merchants can see them in the SparkLayer Dashboard. For example, a product variant with no SKU, or a customer address with an empty first line. |

## Sync endpoints in the Ignite spec

The [Ignite endpoint reference](https://docs.sparklayer.io/ignite/api.md) defines these data sync endpoints on your integration, which SparkLayer calls:

| Endpoint | Method and path | Purpose (from the spec) |
| --- | --- | --- |
| [List entities for a sync](https://docs.sparklayer.io/ignite/api/list-entities.md) | `GET /v1/{siteEnv}/{siteId}/sync/{syncDataType}` | During a full sync, SparkLayer pages through every entity of the type: return one page of entity IDs and a `next_page` value, and an empty `next_page` to end the sync. |
| [Fetch an entity](https://docs.sparklayer.io/ignite/api/fetch-entity.md) | `POST /v1/{siteEnv}/{siteId}/sync/{syncDataType}/{entityId}` | Fetch one entity from the platform, by its platform ID, as SparkLayer customer, product, purchase or stock data. |
| [Trigger a data sync](https://docs.sparklayer.io/ignite/api/trigger-a-data-sync.md) | `POST /v1/{siteEnv}/{siteId}/status/{syncDataType}` | Lets internal users, such as support staff, trigger a manual sync outside the standard process. |

`syncDataType` is one of `customers`, `products`, `purchases` or `stock`.

### How data reaches SparkLayer

SparkLayer pulls the data: during a sync, it lists and fetches customers, products, purchases and stock from your integration with the endpoints above. Stock levels and orders can also be pushed to SparkLayer's [Stock](https://docs.sparklayer.io/developers/api/stock.md) and [Purchasing](https://docs.sparklayer.io/developers/api/purchasing.md) APIs, for example as webhook-driven updates. Products and customers can only reach SparkLayer through **Fetch an entity**: the public API has no endpoints to create them.

## Types of data

The data to sync includes products, pricing, customers, orders and store settings.

### Products

Sync these product fields from the platform:

- `title`
- `slug`
- `external_id`: the platform's product ID
- `variants`
  - `external_id`: the platform's variant ID
  - `sku`
  - `weight_in_grams`
  - `position`
  - `cart_image_url`
  - `options`
  - `status`: `live` when the product is live, and `discontinued` when the product is deleted

SparkLayer fetches products from your integration with [Fetch an entity](https://docs.sparklayer.io/ignite/api/fetch-entity.md), as product data.

Stock levels, from `inventory_level`, are fetched with Fetch an entity as stock data. You can also push them to the SparkLayer Stock API with the [update stock levels endpoint](https://docs.sparklayer.io/developers/api/stock/update-stock-levels.md).

> **Extending the product object with B2B attributes**
>
> If your platform can store extra data, such as attributes (ideally on the variant), it's useful to sync these too:
>
> - `rrp`
> - `settings`
> - `restock_date`: belongs on the stock record, but can be taken from the variant

### Pricing

Sync product pricing to the [SparkLayer Pricing API](https://docs.sparklayer.io/developers/api/pricing.md).

Create at least one price list containing the default price of every product on the platform, named after the platform, such as "BigCommerce Price". Create it when the platform is connected, and update its prices whenever products sync. Create it with `source` set to `integration`.

### Customers

Sync customers and their addresses:

- `external_id`: the platform's customer ID
- `email`
- `first_name`
- `last_name`
- `company_name`
- `send_invite`
- `addresses`

SparkLayer fetches customers from your integration with [Fetch an entity](https://docs.sparklayer.io/ignite/api/fetch-entity.md), as customer data.

> **Extending the customer object with B2B attributes**
>
> If your platform can store extra data, such as attributes, it's useful to sync these too. `group` can also come from another field, such as a customer group on the platform.
>
> - `group`
> - `accounting_id`
> - `sales_agent_groups`
> - `price_lists`
> - `discount_percentage`
> - `payment_on_account`
> - `parent_customer_id`

### Orders

Orders are fetched with Fetch an entity as purchase data. You can also push them with the Purchasing API's [create or update a purchase endpoint](https://docs.sparklayer.io/developers/api/purchasing/create-update-purchase.md), including order creation, amendments and shipments.

For SparkLayer orders, always use the `sparklayer` purchase identifier when you create or update purchases. Other parts of SparkLayer may already have created a purchase for the order without knowing its other identifiers, such as the platform order ID. If you update that purchase with an identifier it wasn't created with, you get a `409 Conflict` error.

It's also useful to sync historical orders that weren't placed through SparkLayer but already exist on the eCommerce platform. For these, it's fine to create the purchase with the `platform` identifier: there's no SparkLayer identifier and no conflicting purchase. Merchants start a historical order import by setting the order import metafield on each order; see [Import order history into SparkLayer](https://docs.sparklayer.io/help/platforms/shopify/metafields.md#import-order-history-into-sparklayer).

### Store settings

When the platform is connected, and whenever the relevant settings change on the eCommerce platform, sync these store settings:

- Base currency: send it with the [update global setting endpoint](https://docs.sparklayer.io/developers/api/core/update-global-setting.md), with the setting key `baseCurrency`.

## Logging sync issues

Report customer and product sync timestamps and errors with the [Sync Logging API](https://docs.sparklayer.io/developers/api/sync-log.md), so merchants can see them in the SparkLayer Dashboard and act on them.

### Full data synchronisation (including initial synchronisation)

Record a full sync with [Record a full sync](https://docs.sparklayer.io/developers/api/sync-log/update-sync-logs-with-a-full-sync.md) (`PUT`). It sets `started_full_sync` and `last_full_sync`, and replaces all previously logged errors with the ones you send.

- **Keep each error's `external_id` unique**, so errors aren't overwritten or resolved by mistake.
- **For a quick, synchronous sync**, send one `PUT` when it finishes, with `started_full_sync`, `last_full_sync` and all the errors.
- **For a long or asynchronous sync**, you won't have every error in one request:
  1. When the sync starts, send a `PUT` with `started_full_sync`. A timestamp you leave out is cleared, so `last_full_sync` is cleared until the sync finishes.
  2. As items sync, record errors (and errors that are now resolved) with [Record a partial sync](https://docs.sparklayer.io/developers/api/sync-log/update-sync-logs-with-a-partial-sync.md) (`PATCH`).
  3. When the whole sync has finished, send a `PATCH` with `last_full_sync` (and the required `last_partial_sync`).
- **If items sync in separate application instances** (for example through a queue), only set `last_full_sync` once every item has synced. The Sync Logging API doesn't track this, so your integration needs to keep track of the items synced and remaining.

### Partial synchronisation

Record a partial sync whenever an individual item syncs, for example when a product or customer is updated on the store and the change is synced to SparkLayer. Use [Record a partial sync](https://docs.sparklayer.io/developers/api/sync-log/update-sync-logs-with-a-partial-sync.md) (`PATCH`). It:

- Keeps the errors already logged
- Adds any new errors
- Resolves errors for the platform IDs you list in `successfully_synced`

Partial sync timestamps are only saved once a full sync has been recorded.

### Deleting sync logs

A full sync clears the previous errors, so you don't normally need to delete sync logs. If a store uninstalls SparkLayer, delete its sync logs with [Delete all sync logs](https://docs.sparklayer.io/developers/api/sync-log/delete-a-stores-sync-logs.md).

## Next steps

- [Endpoints overview](https://docs.sparklayer.io/ignite/endpoints-overview.md): every endpoint your integration implements.
- [Sync Logging API](https://docs.sparklayer.io/developers/api/sync-log.md): the endpoints for recording syncs and errors.


---

# Endpoints overview

URL: https://docs.sparklayer.io/ignite/endpoints-overview

Every endpoint an Ignite integration implements, for platform connection, customers, addresses, checkout, data sync, metafields and authentication.

These are the endpoints your Ignite integration implements for SparkLayer to call. Every path starts with `/v1/{siteEnv}/{siteId}`, where `siteEnv` is the SparkLayer environment (such as `live`) and `siteId` is the merchant's SparkLayer Site ID. For each endpoint's parameters, request body and responses, see the [Ignite endpoint reference](https://docs.sparklayer.io/ignite/api.md).

## Platform connection

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [Connect a platform](https://docs.sparklayer.io/ignite/api/new-platform-connection.md) | `POST /v1/{siteEnv}/{siteId}` | Called when a platform is connected to SparkLayer, either from the SparkLayer Dashboard or when a connection started externally (for example through the platform's SparkLayer app) is complete. The request includes the SparkLayer site environment and ID, and the API credentials. |
| [Disconnect a platform](https://docs.sparklayer.io/ignite/api/remove-platform-connection.md) | `DELETE /v1/{siteEnv}/{siteId}` | Called when a platform is disconnected from SparkLayer. Cancel any data syncs and clean up the connection data in your integration. |

See [Platform connection](https://docs.sparklayer.io/ignite/platform-connection.md) for the full requirements.

## Customers

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [Create or update a customer](https://docs.sparklayer.io/ignite/api/create-update-a-customer.md) | `PUT /v1/{siteEnv}/{siteId}/customers` | Create or update a customer on the eCommerce platform. Use the customer's email address to find them on the platform. |

## Customer sub-accounts

Sub-accounts need customer accounts on the eCommerce platform, which give SparkLayer the same layer of authentication as other accounts. Customers manage their sub-accounts in the frontend interfaces.

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [Create a sub-account](https://docs.sparklayer.io/ignite/api/create-a-new-customer-sub-account.md) | `POST /v1/{siteEnv}/{siteId}/sub-accounts` | Create a customer on the platform and mark it as a sub-account of its parent. |
| [Update a sub-account](https://docs.sparklayer.io/ignite/api/update-an-existing-customer-sub-account.md) | `PATCH /v1/{siteEnv}/{siteId}/sub-accounts/{customer_external_id}` | Change a sub-account's first name, last name and role (not its email address). |
| [Delete a sub-account](https://docs.sparklayer.io/ignite/api/remove-a-customer-sub-account.md) | `DELETE /v1/{siteEnv}/{siteId}/sub-accounts/{customer_external_id}` | Remove a sub-account so it can no longer act for the parent account. |

## Customer addresses

Customers create, update and delete their addresses in the frontend interfaces.

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [Create a customer address](https://docs.sparklayer.io/ignite/api/create-a-new-customer-address.md) | `POST /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses` | Create an address for a customer on the platform. |
| [Update a customer address](https://docs.sparklayer.io/ignite/api/update-a-customer-address.md) | `PUT /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses/{customer_address_external_id}` | Update a customer address on the platform. |
| [Delete a customer address](https://docs.sparklayer.io/ignite/api/remove-a-customer-address.md) | `DELETE /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses/{customer_address_external_id}` | Remove a customer address from the platform. |

## Checkout

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [Calculate tax and shipping](https://docs.sparklayer.io/ignite/api/calculate-tax-and-shipping.md) | `POST /v1/{siteEnv}/{siteId}/checkout/calculate` | Called at the final step of checkout to show the customer tax and the available shipping methods. |
| [Complete checkout](https://docs.sparklayer.io/ignite/api/complete-checkout.md) | `POST /v1/{siteEnv}/{siteId}/checkout/complete` | Called when the customer completes the order. For upfront payment, return a URL to the platform's checkout; otherwise, create the order and return its ID. |

The checkout for upfront payment can be the standard platform checkout, and doesn't need to include discounts and gift cards.

**Important considerations:**

- SparkLayer prices are always tax exclusive. If the platform ever needs checkout prices with tax included, add the tax to the prices SparkLayer sends to the checkout endpoints.
- In the same way, if the shipping prices the platform calculates include tax, account for it, because SparkLayer works with tax-exclusive prices.
- Mark carts, checkouts and orders that your integration creates or updates as coming from SparkLayer, for example with an `external_id` or `source` parameter, or a metafield. Your order sync then uses this to know which orders to sync to SparkLayer.
- Store all the data SparkLayer sends to the checkout endpoints on the platform's cart, checkout or order. Map it to native fields where possible (such as the customer ID or additional order information); use metafields and attributes for data with no native field.

## Data sync

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [List entities for a sync](https://docs.sparklayer.io/ignite/api/list-entities.md) | `GET /v1/{siteEnv}/{siteId}/sync/{syncDataType}` | Called during a full sync to page through every entity of a type. |
| [Fetch an entity](https://docs.sparklayer.io/ignite/api/fetch-entity.md) | `POST /v1/{siteEnv}/{siteId}/sync/{syncDataType}/{entityId}` | Fetch one entity from the platform. |
| [Trigger a data sync](https://docs.sparklayer.io/ignite/api/trigger-a-data-sync.md) | `POST /v1/{siteEnv}/{siteId}/status/{syncDataType}` | Lets internal staff trigger a manual sync from the SparkLayer Dashboard when data needs refreshing. |

See [Data sync](https://docs.sparklayer.io/ignite/data-sync.md) for what to sync and when.

## Metafield configuration

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [Get metafield configuration](https://docs.sparklayer.io/ignite/api/get-metafield-configuration.md) | `GET /v1/{siteEnv}/{siteId}/metafield-configuration` | Return every SparkLayer metafield key the platform supports, and whether each one is configured. |
| [Enable a metafield](https://docs.sparklayer.io/ignite/api/enable-a-metafield.md) | `POST /v1/{siteEnv}/{siteId}/metafield-configuration/enable` | Enable a metafield key on the platform. |

See [Metafields](https://docs.sparklayer.io/developers/data/metafields.md) for the SparkLayer metafield keys.

## Authentication

| Endpoint | Method and path | Purpose |
| --- | --- | --- |
| [Verify storefront authentication](https://docs.sparklayer.io/ignite/api/verify-authentication.md) | `POST /v1/{siteEnv}/{siteId}/authentication/verify` | Verify authentication data from the storefront, such as a JWT, and return the customer's platform ID. |

See [Authentication](https://docs.sparklayer.io/ignite/authentication.md) for how this fits into sign-in.

## Next steps

- [Ignite endpoint reference](https://docs.sparklayer.io/ignite/api.md): each endpoint's parameters, request body and responses.
- [Platform connection](https://docs.sparklayer.io/ignite/platform-connection.md): the first endpoints SparkLayer calls.


---

# Ignite endpoints

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

Reference for the endpoints your Ignite service implements for SparkLayer to call: platform connection, customers, addresses, checkout, sync and authentication.

This reference lists every endpoint your Ignite integration implements, with its parameters, request body and responses. For what each one is for, see the [Endpoints overview](https://docs.sparklayer.io/ignite/endpoints-overview.md).

_Every operation is listed under "API operations" at the top of this file._

## Next steps

- [Endpoints overview](https://docs.sparklayer.io/ignite/endpoints-overview.md): what each endpoint is for.
- [Platform connection](https://docs.sparklayer.io/ignite/platform-connection.md): the first endpoints SparkLayer calls.