Skip to content

Platform connection

Steps for
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.

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.

  1. The merchant installs the SparkLayer app on their store.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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)).

  1. SparkLayer calls your integration's Connect a platform endpoint with the SparkLayer site and credentials.
  2. Your integration stores this data and returns a redirect_url, where the merchant installs the SparkLayer app on the platform.
  3. Once the app is installed, your integration stores the store's credentials and other data it needs.
  4. 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.
  5. 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:

FieldDescription
store_idThe store's ID on the platform
spark_api_client_id and spark_api_client_secretAPI credentials your integration uses to call the SparkLayer API for this site
extra_config, magento_*Platform-specific credentials for WooCommerce and Magento

Respond with:

  • 201 and a redirect_url when the connection is pending: the SparkLayer Dashboard redirects the merchant there to install the SparkLayer app on the platform
  • 204 when 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):

  1. Register any data change webhooks with the platform, if it has them.
  2. Sync the store settings from the platform to the SparkLayer API.
  3. 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_url to 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:

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.
Was this page helpful?

Last updated