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

> **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, and the Customers API (`/api/v2/customers`) over the legacy `DELETE /api/v1/customers` in the Core API. 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:** `customers`, `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.

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 to ask for a fresh sync of products or customers.

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 SparkLayer ask for a 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.
