Skip to content

Ignite data sync

For AI assistants: the facts every SparkLayer API call needs
  • 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 409s 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: 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

AreaNotes
Queueing and retryRetry partial sync events if they fail, so the platform stays stable and reliable.
PerformanceDesign 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.
ReportingLog the last updated date and the last full sync with the Sync Logging API, as described in Logging sync issues.
Issue loggingHandle 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:

EndpointMethod and pathPurpose (from the spec)
List entities for a syncGET /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 entityPOST /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 syncPOST /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:

  • 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, 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:

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

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, 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, 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:

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_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 (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 (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

Was this page helpful?

Last updated