Platform connection
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.
A platform connection links an eCommerce platform store to a SparkLayer site. SparkLayer calls two endpoints on your integration: one when a platform is connected, and one when it's removed. A new connection can start from the eCommerce platform or from the SparkLayer Dashboard, and your integration needs to support both flows.
Platform connection flows
Initiated through the eCommerce platform
The merchant starts the connection from the platform's app store (or similar), for example by installing the SparkLayer app on BigCommerce or Shopify. This flow only applies if your platform supports third-party apps.
This flow uses the SparkLayer Dashboard API to register the user with SparkLayer, create a platform connection between the platform and a SparkLayer site, and get the site's onboarding progress. Its documentation isn't public, but we can provide it on request.
- The merchant installs the SparkLayer app on their store.
- Your integration stores the store's credentials and other data it needs, usually the store identifier and the platform's API access token or credentials.
- The SparkLayer app on the platform shows the user a SparkLayer registration page. To register the user, call the Dashboard API's user registration endpoint.
- When registration succeeds, SparkLayer returns the site environment and Site ID. Use them to call the Dashboard API's site platform connection endpoint, which links the store to the new SparkLayer site.
- SparkLayer calls your integration's Connect a platform endpoint with the Site ID and credentials. Store them and run the connection completion actions, such as a full data sync.
- The connection is complete. In the platform's SparkLayer app, show the user the SparkLayer onboarding steps, with links to the SparkLayer Dashboard and the Help Center. Get the onboarding progress from the Dashboard API's onboarding steps endpoint.
Initiated through the SparkLayer Dashboard
The merchant starts the connection from the eCommerce platform page of an existing SparkLayer site in the SparkLayer Dashboard (Integrations,Platform (opens in your SparkLayer Dashboard in a new tab)).
- SparkLayer calls your integration's Connect a platform endpoint with the SparkLayer site and credentials.
- Your integration stores this data and returns a
redirect_url, where the merchant installs the SparkLayer app on the platform. - Once the app is installed, your integration stores the store's credentials and other data it needs.
- Your integration now has both the SparkLayer and the platform data, so the connection is complete and it can start actions such as a full data sync.
- Show the user the SparkLayer onboarding steps and progress, from the Dashboard API's onboarding steps endpoint.
Platform connection endpoints
SparkLayer calls these endpoints to tell your integration about a new or removed platform connection.
New platform connection
Connect a platform (POST /v1/{siteEnv}/{siteId}) records the new connection, and runs the completion actions if the connection is complete.
The request body includes:
| Field | Description |
|---|---|
store_id | The store's ID on the platform |
spark_api_client_id and spark_api_client_secret | API credentials your integration uses to call the SparkLayer API for this site |
extra_config, magento_* | Platform-specific credentials for WooCommerce and Magento |
Respond with:
201and aredirect_urlwhen the connection is pending: the SparkLayer Dashboard redirects the merchant there to install the SparkLayer app on the platform204when the app is already installed and the connection is now active
Once the connection is complete (your integration has the SparkLayer and platform configuration and credentials, and can start syncing data):
- Register any data change webhooks with the platform, if it has them.
- Sync the store settings from the platform to the SparkLayer API.
- Start a full sync of customers and products.
Important considerations:
- The connection may not be complete when SparkLayer calls this endpoint: for example, when the connection starts in the SparkLayer Dashboard and the merchant still has to finish it on the platform. In that case, return a
redirect_urlto the platform's SparkLayer installation page, where the merchant links their store to the pending connection. - The endpoint must be idempotent, because SparkLayer may call it more than once. If the connection is already established, re-trigger the completion actions safely.
Remove platform connection
Disconnect a platform (DELETE /v1/{siteEnv}/{siteId}) should:
- Stop processing any syncs
- Delete the store's sync logs
- Delete the connection data stored by your integration
Authentication between SparkLayer and your integration
Calls from your integration to SparkLayer. Use the spark_api_client_id and spark_api_client_secret from the connect request to get OAuth access tokens, as described in Authentication. Tokens are short-lived, so store them with the connection data and refresh them when they expire.
Calls from SparkLayer to your integration. The Ignite spec lists 401 Auth Failure responses for these endpoints, but doesn't define how SparkLayer authenticates its requests.
Next steps
- Authentication: verify customers signed in to your platform.
- Data sync: the full sync to run once the connection is complete.
Last updated