Skip to content
Ignite endpoints

Complete checkout

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. 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: 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.
Build with AI: ready-made prompts and MCP setup

Implemented by your integration

This is an Ignite endpoint: your integration service implements it and SparkLayer calls it. Use this reference to build and test your implementation.
POST/v1/{siteEnv}/{siteId}/checkout/complete

This endpoint is called at the final step once the customer attempts to complete the order. If the payment type is upfrontPayment the customer should be directed to the checkout flow to complete payment. Alternatively, an order can be created there and then for other systems to manage payments.

At this point, either redirect the user to a URL to complete the transaction or return a ID of the order being created on the platform.

Path Parameters

siteEnv*string

The SparkLayer environment the request is for, such as live. Store it, with the site ID, when SparkLayer connects your platform.

siteId*string

The SparkLayer site ID the request is for, such as bobs-store. Store it, with the environment, when SparkLayer connects your platform.

Length1 <= length

Request Body

application/json

Checkout

TypeScript Definitions

Use the request body type in TypeScript.

cart_id?string

SparkLayer Cart ID

Formatuuid
customer?
currency_code?string

ISO 4217 currency code

Length3 <= length <= 3
billing_address?
shipping_address?
shipping_line?|

If using platform shipping, on the first load of the final checkout screen, this will be null, after it will be an ID from a method from the response of available_shipping_methods If using SparkLayer shipping, this can be null if none found or will be the method.

internal_shipping_methods?array<>|
Deprecated

List of available SparkLayer shipping methods for the given checkout, if not using spark shipping this will be empty.

shop?
line_items?array<|>
ignite_state?

Context which was set by a previous response from /checkout/calculate

ignite_checkout_context?|

Extra context provided by the checkout frontend. This allows passing arbitrary platform-specific data that might be needed by the platform's checkout process. For example, for BigCommerce, this could be used to pass a channel_id from the store theme to the ignite integration in order to support multi-channel stores.

shipping_method_source?string

Specifies the store's configured source for retrieving shipping methods during checkout. When sparklayer, a null shipping_line means the cart has no shipping charge, and no platform rate is fetched or applied. Absent is treated as platform.

Value in

  • "sparklayer"
  • "platform"
payment_type?string

Value in

  • "upfrontPayment"
  • "paymentOnAccount"
  • "paymentByInvoice"
  • "quote"
sales_agent?|null
company_user?|null
additional_info?|

An optional note to be added to the order.

po_number?|

PO number for the purchase

shipping_requested_date?|

The date requested for the delivery to arrive

Formatdate-time
custom_fields?|

Custom fields to be added to the order. These are customer defined and dynamic.

discount_data?|null
discount_coupon_codes?array<>|

A list of all the coupon codes applied to the order

Response Body

application/json

curl -X POST "https://ignite.example.com/v1/live/bobs-store/checkout/complete" \  -H "Content-Type: application/json" \  -d '{    "cart_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",    "customer": {      "id": "cu_1",      "email": "buyer@example.com",      "external_id": "CUS1234",      "accounting_id": "<accounting_id>",      "default_billing_address_id": "<default_billing_address_id>",      "default_shipping_address_id": "<default_shipping_address_id>",      "temporary_external_address_ids": [        "<temporary_external_address_ids>"      ],      "payment_on_account": {        "credit_limit": 0,        "balance": 0,        "currency_code": "<currency_code>",        "net_terms": "7_days"      }    },    "currency_code": "gbp",    "billing_address": {      "title": "Mr",      "first_name": "Bob",      "last_name": "Jones",      "company": "Tom Jones Climbing Ltd",      "address_line1": "Example Industrial Estate",      "address_line2": "North Country",      "city": "Cityland",      "region_name": "California",      "region_code": "CA",      "postal_code": "12345",      "country_code": "US",      "phone": "+44 (0) 123456789",      "is_default_shipping": true,      "is_default_billing": true,      "is_temporary": true    },    "shipping_address": {      "title": "Mr",      "first_name": "Bob",      "last_name": "Jones",      "company": "Tom Jones Climbing Ltd",      "address_line1": "Example Industrial Estate",      "address_line2": "North Country",      "city": "Cityland",      "region_name": "California",      "region_code": "CA",      "postal_code": "12345",      "country_code": "US",      "phone": "+44 (0) 123456789",      "is_default_shipping": true,      "is_default_billing": true,      "is_temporary": true    },    "shipping_line": {      "type": "platform",      "id": "<id>",      "name": "<name>",      "price": 4.8,      "tax_rate": 0.2    },    "internal_shipping_methods": [      {        "title": "<title>",        "price_v2": {          "tax_rate": 0,          "net": 0,          "gross": 0,          "currency_code": "<currency_code>"        },        "handle": "<handle>",        "cost_type": "<cost_type>",        "cost_language_string": "<cost_language_string>"      }    ],    "shop": {      "base_currency_code": "gbp"    },    "line_items": [      {        "type": "product",        "spark_item_key": "00a0c91e6bf600a0c91e6bf",        "spark_variant_id": "8ac52999-d163-4d68-ae30-a5f0c089ed79",        "sku": "EXAMPLE-SKU",        "product_variant_external_id": "PROD123456",        "product_external_id": "PROD1234",        "quantity": 10,        "unit_price": 4.8,        "custom_attributes": [          {            "key": "<key>",            "value": "<value>"          }        ],        "options": [          {            "group": "<group>",            "value": "<value>"          }        ]      }    ],    "ignite_state": {},    "ignite_checkout_context": {      "channel_id": 12345    },    "shipping_method_source": "sparklayer",    "payment_type": "upfrontPayment",    "sales_agent": {      "id": "cu_1",      "email": "buyer@example.com",      "accounting_id": "<accounting_id>"    },    "company_user": {      "id": "cu_1",      "email": "buyer@example.com",      "external_id": "CUS1234",      "accounting_id": "<accounting_id>"    },    "additional_info": "<additional_info>",    "po_number": "PO-001",    "shipping_requested_date": "2020-01-01T00:00:00+02:00",    "custom_fields": {},    "discount_data": {      "sub_total_pre_discount": {        "net": 0      },      "sub_total_discount": {        "net": 0      },      "shipping_pre_discount": {        "net": 0      },      "shipping_discount": {        "net": 0      },      "line_item_discounts": [        {          "pre_discount": {            "net": 0          },          "discount": {            "net": 0          },          "sku": "<sku>",          "item_key": "<item_key>"        }      ],      "discount_slugs": [        "<discount_slugs>"      ]    },    "discount_coupon_codes": [      "<discount_coupon_codes>"    ]  }'
{  "line_items": [    {      "spark_item_key": "string",      "tax_lines": [        {          "rate": 0.2,          "price": 1        }      ]    }  ],  "platform_shipping_line": {    "type": "platform",    "id": "string",    "name": "string",    "price": 4.8,    "tax_rate": 0.2  },  "checkout_url": "https://checkout-bobs-store.com/checkout/1234/payment"}

POSTCalculate tax and shipping

This endpoint is called at the final step of the checkout process in order to show tax and shipping methods available to the customer.

GETList entities for a sync

SparkLayer calls this endpoint during a full sync to page through every entity of the given type. Return one page of entities and a `next_page` value; SparkLayer requests the next page with it in the `page` query parameter. Return an empty string or `null` for `next_page` to end the sync.