Purchasing API
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. - 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.
The Purchasing API stores your customers' purchases: carts, quotes, purchases awaiting approval or confirmation, and placed orders. Use it to keep the orders shown in My Account up to date.
Purchases aren't sent to your eCommerce platform
Purchases you create with this API show in the My Account area for your B2B customers, but SparkLayer doesn't push them to your eCommerce platform (such as Shopify). To have an order on your platform too, create it with the platform's own API, such as the Shopify order API (opens in a new tab).
For orders created on your platform to sync to SparkLayer, they need a few properties, which depend on your platform. On Shopify, each order needs:
- The
b2btag - The
sparklayer.order_importmetafield, set totrue
See Import order history into SparkLayer for the Shopify steps.
Common uses
| You want to | What to do |
|---|---|
| Show orders placed outside SparkLayer, such as phone orders keyed into your ERP or orders from another channel, in the customer's order history in My Account | Send each one with Create or update a purchase, as type order. They also count in Pulse. See Send orders to SparkLayer. |
| Import past orders once, so customers and Pulse see their full history | Send each order as above, once. See Import order history. |
| Show that an order has been paid when you record payments elsewhere, such as in your ERP or accounting system | Create a transaction against the purchase with Create or update a purchase transaction, with apply_to_balance set to true. See Purchase transactions. |
| Look up an order's status in SparkLayer from another system | Call Get a purchase with lookupBy set to platform and the order's ID on your eCommerce platform, such as the Shopify order ID, as the identifier. |
| Place orders through SparkLayer's cart and checkout, with its pricing and ordering rules | Use the Ordering API instead. |
Creating and updating purchases
Create and update purchases with Create or update a purchase (PUT /api/v1/purchases/{lookupBy}/{identifier}). If no purchase matches lookupBy and identifier, a new one is created.
- Send the full purchase every time. The request replaces the purchase's previous data, so include every field, not just the ones that changed. This prevents stale data and keeps order integrations simple.
- Leave out calculated fields. The API calculates them, so don't set them in the request body.
- Expect a
400for missing or invalid values. The error identifies the value to fix.
Purchase identifiers
The purchase_identifiers object holds the purchase's IDs in each system. Use one of them as lookupBy:
| Identifier | Description |
|---|---|
sparklayer | SparkLayer's ID for the purchase (a UUID). For an order placed through SparkLayer, this is the ID of the SparkLayer cart, which SparkLayer passes to your eCommerce platform when the customer completes checkout. Send it so the order moves from awaiting_merchant to order and replaces the cart. For other orders, leave it out: SparkLayer generates one when it creates the purchase. |
platform | The purchase's ID on your eCommerce platform. |
internal | Your ID for the purchase, such as the order number in your ERP or order management system (OMS). |
visible | The ID shown to the customer in their recent orders. |
- The body must contain the identifier in the URL. A
PUTto/api/v1/purchases/internal/SO-10452needs"internal": "SO-10452"inpurchase_identifiers. - Lookups are exact and case-sensitive, and identifiers can be up to 64 characters.
- Keep identifiers unique. SparkLayer doesn't stop 2 purchases sharing one, and a lookup by a shared identifier finds either of them. Never send a new
sparklayerID each time you send a purchase: every request then creates a copy.
Purchase types
Most integrations send purchases of type order.
| Purchase type | Description |
|---|---|
quote | A quote, with a quote status. |
awaiting_approval | A purchase waiting for another person at the customer's company to approve it, typically with company users. |
awaiting_merchant | An order completed in SparkLayer but not yet confirmed, because it's pending on the eCommerce platform or the sync hasn't finished. |
order | A finalised order, saved on the eCommerce platform or in your order source of truth, such as an ERP or OMS. |
Packages
A purchase is mostly made up of packages, which hold the line items, shipping methods, addresses and IDs. Each package is one thing that happened to some of the items.
- When you first create an order, put its line items in a
processingpackage. - As the order progresses, move items into a
shipmentpackage for each shipment, with itsshipped_at, or acancelledpackage with itscancelled_at. You can have more than one of each, for example for partial shipments. - When items come back, keep them in their shipment and list them again in a
returnpackage, with itsreturn_started_at.
The order status customers see, calculated_fulfilment_status, is calculated from the package dates, not the package types: a cancelled package with no cancelled_at counts as processing. See Send orders to SparkLayer for the rules, how each status is worked out, and a complete example.
Purchase transactions
Record payments, refunds and other transactions against a purchase with Create or update a purchase transaction. SparkLayer uses the transactions to calculate the purchase's payment status.
If you record transactions with this API, don't also send them to your eCommerce platform: the same transaction could be recorded twice.
- Identify the purchase in the request URL, with
lookupByandidentifier. A purchase can have many transactions, but each needs a uniqueplatform_id: the ID the third-party system (such as your payment provider) uses for the transaction.purchase_spark_idin the response is read-only, so don't send it. - Set the amount in
amount, as a string: positive for a payment, negative for a refund. Acurrency_codeandtransaction_dateare also required. - Choose whether it counts with
apply_to_balance.
apply_to_balance | What happens |
|---|---|
false | The transaction is stored for information only, and isn't used to calculate the payment status. The list endpoint returns it, but nothing else happens. Use this for pending or failed transactions, which can help with debugging. |
true | The transaction counts towards the purchase's payment status. SparkLayer also adds an entry to the purchase history, which the customer sees, and adjusts the outstanding balance of the purchase's customer by the total. |
Changing a transaction from true to false deletes the history entry it created, and reverses the change to the customer's balance and payment status.
Use full_transaction to store the full transaction, as a JSON string, as the third-party system holds it. SparkLayer stores it as given, without redacting anything, so remove or obscure sensitive data, such as full card numbers, before you send it.
Endpoints
Purchasing
Next steps
- Authentication: get an access token for your requests.
- Ordering API: place orders on behalf of customers.
- Files API: download the files customers attach to orders.
Last updated