Ignite data sync
For AI assistants: the facts every SparkLayer API call needs
- Base URLs: Live
https://app.sparklayer.io, testhttps://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/tokenwith aSite-Idheader and a JSON body (not form-encoded):{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}. It returnsaccess_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>andSite-Id: <site id>, plusContent-Type: application/jsonwhen there is a body. Set aUser-Agentthat names your integration. - Errors: RFC 7807 problem details:
title,status,detailand an optionalerrors[]of{ code, message, property }. Some error responses have no body. Retry5xx,429(honouringRetry-After) and concurrent-update409s with exponential backoff; on401, get a new token once and retry; don't retry other4xxwithout changing the request. - Pagination: Most list endpoints return everything.
GET /api/v2/price-listspages withpageandpage_size(up to 250) untilpagination.current_pageequalstotal_pages.GET /api/v1/purchasesuseslimit(up to 500) andoffset: stop when a page has fewer thanlimitresults. - Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer
GET /api/v2/price-listsover the deprecated v1, and the Customers API (/api/v2/customers) over the legacyDELETE /api/v1/customersin 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
.mdto any page URL. Index of every page: docs.sparklayer.io/llms.txt. Every API operation, compactly: docs.sparklayer.io/llms-api.txt. The developer guides in full: 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, and the SparkLayer Frontend 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 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, as described in 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 defines these data sync endpoints on your integration, which SparkLayer calls:
| Endpoint | Method and path | Purpose (from the spec) |
|---|---|---|
| List entities for a sync | 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 | 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 | 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 and Purchasing 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:
titleslugexternal_id: the platform's product IDvariantsexternal_id: the platform's variant IDskuweight_in_gramspositioncart_image_urloptionsstatus:livewhen the product is live, anddiscontinuedwhen the product is deleted
SparkLayer fetches products from your integration with Fetch an entity, 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.
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:
rrpsettingsrestock_date: belongs on the stock record, but can be taken from the variant
Pricing
Sync product pricing to the SparkLayer Pricing API.
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 IDemailfirst_namelast_namecompany_namesend_inviteaddresses
SparkLayer fetches customers from your integration with Fetch an entity, 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.
groupaccounting_idsales_agent_groupsprice_listsdiscount_percentagepayment_on_accountparent_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, 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.
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, with the setting key
baseCurrency.
Logging sync issues
Report customer and product sync timestamps and errors with the Sync Logging API, 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 (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_idunique, so errors aren't overwritten or resolved by mistake. - For a quick, synchronous sync, send one
PUTwhen it finishes, withstarted_full_sync,last_full_syncand all the errors. - For a long or asynchronous sync, you won't have every error in one request:
- When the sync starts, send a
PUTwithstarted_full_sync. A timestamp you leave out is cleared, solast_full_syncis cleared until the sync finishes. - As items sync, record errors (and errors that are now resolved) with Record a partial sync (
PATCH). - When the whole sync has finished, send a
PATCHwithlast_full_sync(and the requiredlast_partial_sync).
- When the sync starts, send a
- If items sync in separate application instances (for example through a queue), only set
last_full_synconce 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 (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.
Next steps
- Endpoints overview: every endpoint your integration implements.
- Sync Logging API: the endpoints for recording syncs and errors.
Last updated