Endpoints overview
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.
These are the endpoints your Ignite integration implements for SparkLayer to call. Every path starts with /v1/{siteEnv}/{siteId}, where siteEnv is the SparkLayer environment (such as live) and siteId is the merchant's SparkLayer Site ID. For each endpoint's parameters, request body and responses, see the Ignite endpoint reference.
Platform connection
| Endpoint | Method and path | Purpose |
|---|---|---|
| Connect a platform | POST /v1/{siteEnv}/{siteId} | Called when a platform is connected to SparkLayer, either from the SparkLayer Dashboard or when a connection started externally (for example through the platform's SparkLayer app) is complete. The request includes the SparkLayer site environment and ID, and the API credentials. |
| Disconnect a platform | DELETE /v1/{siteEnv}/{siteId} | Called when a platform is disconnected from SparkLayer. Cancel any data syncs and clean up the connection data in your integration. |
See Platform connection for the full requirements.
Customers
| Endpoint | Method and path | Purpose |
|---|---|---|
| Create or update a customer | PUT /v1/{siteEnv}/{siteId}/customers | Create or update a customer on the eCommerce platform. Use the customer's email address to find them on the platform. |
Customer sub-accounts
Sub-accounts need customer accounts on the eCommerce platform, which give SparkLayer the same layer of authentication as other accounts. Customers manage their sub-accounts in the frontend interfaces.
| Endpoint | Method and path | Purpose |
|---|---|---|
| Create a sub-account | POST /v1/{siteEnv}/{siteId}/sub-accounts | Create a customer on the platform and mark it as a sub-account of its parent. |
| Update a sub-account | PATCH /v1/{siteEnv}/{siteId}/sub-accounts/{customer_external_id} | Change a sub-account's first name, last name and role (not its email address). |
| Delete a sub-account | DELETE /v1/{siteEnv}/{siteId}/sub-accounts/{customer_external_id} | Remove a sub-account so it can no longer act for the parent account. |
Customer addresses
Customers create, update and delete their addresses in the frontend interfaces.
| Endpoint | Method and path | Purpose |
|---|---|---|
| Create a customer address | POST /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses | Create an address for a customer on the platform. |
| Update a customer address | PUT /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses/{customer_address_external_id} | Update a customer address on the platform. |
| Delete a customer address | DELETE /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses/{customer_address_external_id} | Remove a customer address from the platform. |
Checkout
| Endpoint | Method and path | Purpose |
|---|---|---|
| Calculate tax and shipping | POST /v1/{siteEnv}/{siteId}/checkout/calculate | Called at the final step of checkout to show the customer tax and the available shipping methods. |
| Complete checkout | POST /v1/{siteEnv}/{siteId}/checkout/complete | Called when the customer completes the order. For upfront payment, return a URL to the platform's checkout; otherwise, create the order and return its ID. |
The checkout for upfront payment can be the standard platform checkout, and doesn't need to include discounts and gift cards.
Important considerations:
- SparkLayer prices are always tax exclusive. If the platform ever needs checkout prices with tax included, add the tax to the prices SparkLayer sends to the checkout endpoints.
- In the same way, if the shipping prices the platform calculates include tax, account for it, because SparkLayer works with tax-exclusive prices.
- Mark carts, checkouts and orders that your integration creates or updates as coming from SparkLayer, for example with an
external_idorsourceparameter, or a metafield. Your order sync then uses this to know which orders to sync to SparkLayer. - Store all the data SparkLayer sends to the checkout endpoints on the platform's cart, checkout or order. Map it to native fields where possible (such as the customer ID or additional order information); use metafields and attributes for data with no native field.
Data sync
| Endpoint | Method and path | Purpose |
|---|---|---|
| List entities for a sync | GET /v1/{siteEnv}/{siteId}/sync/{syncDataType} | Called during a full sync to page through every entity of a type. |
| Fetch an entity | POST /v1/{siteEnv}/{siteId}/sync/{syncDataType}/{entityId} | Fetch one entity from the platform. |
| Trigger a data sync | POST /v1/{siteEnv}/{siteId}/status/{syncDataType} | Lets SparkLayer ask for a sync when data needs refreshing. |
See Data sync for what to sync and when.
Metafield configuration
| Endpoint | Method and path | Purpose |
|---|---|---|
| Get metafield configuration | GET /v1/{siteEnv}/{siteId}/metafield-configuration | Return every SparkLayer metafield key the platform supports, and whether each one is configured. |
| Enable a metafield | POST /v1/{siteEnv}/{siteId}/metafield-configuration/enable | Enable a metafield key on the platform. |
See Metafields for the SparkLayer metafield keys.
Authentication
| Endpoint | Method and path | Purpose |
|---|---|---|
| Verify storefront authentication | POST /v1/{siteEnv}/{siteId}/authentication/verify | Verify authentication data from the storefront, such as a JWT, and return the customer's platform ID. |
See Authentication for how this fits into sign-in.
Next steps
- Ignite endpoint reference: each endpoint's parameters, request body and responses.
- Platform connection: the first endpoints SparkLayer calls.
Last updated