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

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

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.