Skip to content

Endpoints overview

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.

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

EndpointMethod and pathPurpose
Connect a platformPOST /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 platformDELETE /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

EndpointMethod and pathPurpose
Create or update a customerPUT /v1/{siteEnv}/{siteId}/customersCreate 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.

EndpointMethod and pathPurpose
Create a sub-accountPOST /v1/{siteEnv}/{siteId}/sub-accountsCreate a customer on the platform and mark it as a sub-account of its parent.
Update a sub-accountPATCH /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-accountDELETE /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.

EndpointMethod and pathPurpose
Create a customer addressPOST /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addressesCreate an address for a customer on the platform.
Update a customer addressPUT /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses/{customer_address_external_id}Update a customer address on the platform.
Delete a customer addressDELETE /v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses/{customer_address_external_id}Remove a customer address from the platform.

Checkout

EndpointMethod and pathPurpose
Calculate tax and shippingPOST /v1/{siteEnv}/{siteId}/checkout/calculateCalled at the final step of checkout to show the customer tax and the available shipping methods.
Complete checkoutPOST /v1/{siteEnv}/{siteId}/checkout/completeCalled 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_id or source parameter, 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

EndpointMethod and pathPurpose
List entities for a syncGET /v1/{siteEnv}/{siteId}/sync/{syncDataType}Called during a full sync to page through every entity of a type.
Fetch an entityPOST /v1/{siteEnv}/{siteId}/sync/{syncDataType}/{entityId}Fetch one entity from the platform.
Trigger a data syncPOST /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

EndpointMethod and pathPurpose
Get metafield configurationGET /v1/{siteEnv}/{siteId}/metafield-configurationReturn every SparkLayer metafield key the platform supports, and whether each one is configured.
Enable a metafieldPOST /v1/{siteEnv}/{siteId}/metafield-configuration/enableEnable a metafield key on the platform.

See Metafields for the SparkLayer metafield keys.

Authentication

EndpointMethod and pathPurpose
Verify storefront authenticationPOST /v1/{siteEnv}/{siteId}/authentication/verifyVerify 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

Was this page helpful?

Last updated