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

> **For AI assistants:** these facts apply to every SparkLayer API call.
>
> - **Base URLs:** Live `https://app.sparklayer.io`, test `https://test.app.sparklayer.io`. Each environment has its own data and its own API keys.
> - **Access:** API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
> - **Access token:** `POST {base}/api/auth/token` with a `Site-Id` header and a JSON body (not form-encoded): `{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}`. It returns `access_token`, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
> - **Every request:** `Authorization: Bearer <access_token>` and `Site-Id: <site id>`, plus `Content-Type: application/json` when there is a body. Set a `User-Agent` that names your integration.
> - **Errors:** RFC 7807 problem details: `title`, `status`, `detail` and an optional `errors[]` of `{ code, message, property }`. Some error responses have no body. Retry `5xx`, `429` (honouring `Retry-After`) and concurrent-update `409`s with exponential backoff; on `401`, get a new token once and retry; don't retry other `4xx` without changing the request.
> - **Pagination:** Most list endpoints return everything. `GET /api/v2/price-lists` pages with `page` and `page_size` (up to 250) until `pagination.current_page` equals `total_pages`. `GET /api/v1/purchases` uses `limit` (up to 500) and `offset`: stop when a page has fewer than `limit` results.
> - **Ground rules:** Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer `GET /api/v2/price-lists` over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.
> - **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.

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.