Skip to content
API referencePurchasing API

Create or update a purchase

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.
  • 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
PUT
/api/v1/purchases/{lookupBy}/{identifier}

Creates the purchase if none matches lookupBy and identifier, otherwise replaces it, and returns the stored purchase. The request replaces all of the purchase's data, so always send the full purchase rather than only the fields that changed, and leave out calculated fields: the API calculates them. For an order placed through SparkLayer, look it up with lookupBy=sparklayer and the SparkLayer cart ID, so the order replaces the cart.

Purchases created here appear in My Account but aren't sent to your eCommerce platform. Returns 400 if a required value is missing or invalid, 403 if the request tries to change the purchase's SparkLayer ID, and 409 if it conflicts with the stored purchase.

Authorization

bearerAuth
AuthorizationBearer <token>

Send Authorization: Bearer <access_token>, together with your Site-Id header, on every request. Get the token from POST /api/auth/token with your Site ID in the Site-Id header and a JSON body (not form-encoded, so standard OAuth 2.0 client libraries don't work): {"grant_type": "client_credentials", "client_id": "…", "client_secret": "…"}. Tokens are valid for 3,600 seconds and there is no refresh token: request a new one shortly before it expires. Create API credentials in the SparkLayer Dashboard under Settings > API. See Authentication.

In: header

Path Parameters

lookupBy*string

Which of the purchase's purchase_identifiers identifier is: sparklayer, platform, internal or visible.

Value in

  • "sparklayer"
  • "platform"
  • "internal"
  • "visible"
identifier*|

The purchase identifier, of the kind set by lookupBy. With lookupBy=sparklayer it must be a UUID.

Header Parameters

Site-Id*string

Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

SparkLayer purchase object

type*PurchaseType

Value in

  • "quote"
  • "cart"
  • "awaiting_approval"
  • "order"
  • "awaiting_merchant"
  • "archived"
  • "platform_archived"
  • "pending_recurring_order"
purchase_identifiers*
customer_identifiers*
company?|

Company sections are opt-in; omit this entirely for merchants that do not use them.

payment_method?|

How the purchase was/will be paid for

Value in

  • "quote"
  • "upfrontPayment"
  • "paymentOnAccount"
  • "paymentByInvoice"
dates*
customer_reference?|

Additional information that a customer adds to the order

po_number?|

PO number for the purchase

shipping_requested_date?|

The date requested for the delivery to arrive

Formatdate-time
recurring_purchase?|

Present only for a purchase created from a recurring purchase template. Both properties are stored when the purchase is created and ignored on any later update

currency_code?|

The 3 letter currency code used for the prices in the purchase

Length3 <= length <= 3
currency_code_base?|

The 3 letter currency code of the store's base currency

Length3 <= length <= 3
calculated_total?

Gross total price of the purchase, calculated by SparkLayer based on package and shipment costs. This is read only - it should not be sent to the API, but will be returned form it

calculated_total_usd?

Gross total price in USD of the purchase, calculated by SparkLayer based on package and shipment costs. This is read only - it should not be sent to the API, but will be returned form it

calculated_total_base?

Gross total price in the store's base currency, calculated by SparkLayer. This is read only - it should not be sent to the API, but will be returned from it

quote?|

Quote data

payment_status?string

That payment status of the order

Value in

  • "unpaid"
  • "part_paid"
  • "paid"
total_paid?
revision_date?|

The date at which the purchase was last modified - include user timezone or Z for UTC (RFC-3339)

Formatdate-time
tax_lines?array<>

Tax lines for the purchase.

billing_address?|null
packages*array<||||>

Packages contained within this purchase

accounting_files*array<>

Any accounting files associated with this package e.g. invoices

custom_fields*array<>

Extra information for the purchase. This will be shown to the customer in their recent orders

metadata?array<>

Extra information for the purchase. This not will be shown to the customer

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X PUT "https://app.sparklayer.io/api/v1/purchases/platform/123456789" \  -H "Authorization: Bearer <ACCESS_TOKEN>" \  -H "Site-Id: jones-climbing" \  -H "Content-Type: application/json" \  -d '{    "type": "order",    "purchase_identifiers": {      "sparklayer": "63428136-658f-48a6-beb7-7f333dfd9686",      "platform": "123456789",      "internal": "<internal>",      "visible": "B2B01123"    },    "customer_identifiers": {      "sparklayer": "4217ba4f-7618-4e3b-b1af-9055639b18d1",      "sparklayer_impersonator": "4217ba4f-7618-4e3b-b1af-9055639b18d1",      "sparklayer_impersonator_assignee": "4217ba4f-7618-4e3b-b1af-9055639b18d1",      "sparklayer_child": "4217ba4f-7618-4e3b-b1af-9055639b18d1"    },    "company": {      "id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",      "section_id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",      "section_name": "Bristol"    },    "payment_method": "quote",    "dates": {      "placed_at": "2020-01-01T00:00:00+02:00",      "to_be_placed_at": "2020-01-01T00:00:00+02:00",      "payment_due_at": "2020-01-01T00:00:00+02:00"    },    "customer_reference": "Please deliver to the back of the store",    "po_number": "PO-001",    "shipping_requested_date": "2020-01-01T00:00:00+02:00",    "recurring_purchase": {      "template_id": "0f8fad5b-d9cb-469f-a165-70867728950e",      "cancelled_at": "2020-01-01T00:00:00+02:00",      "to_be_placed_at_initial": "2020-01-01T00:00:00+02:00"    },    "currency_code": "GBP",    "currency_code_base": "GBP",    "calculated_total": {      "number": "15.99",      "currency": "GBP"    },    "calculated_total_usd": {      "number": "15.99",      "currency": "GBP"    },    "calculated_total_base": {      "number": "15.99",      "currency": "GBP"    },    "quote": {      "status_slug": "<status_slug>",      "status": {        "id": "<id>",        "name": "<name>",        "slug": "<slug>",        "default": true,        "next": "<next>",        "actions": [          "edit_quote"        ],        "created_at": "2026-01-31T09:00:00Z",        "updated_at": "2026-01-31T09:00:00Z",        "deleted_at": "2026-01-31T09:00:00Z"      },      "expiry": "2020-01-01T00:00:00+02:00"    },    "payment_status": "unpaid",    "total_paid": {      "number": "15.99",      "currency": "GBP"    },    "revision_date": "2020-01-01T00:00:00+02:00",    "tax_lines": [      {        "title": "HST",        "amount": {          "number": "15.99",          "currency": "GBP"        },        "amount_base": {          "number": "15.99",          "currency": "GBP"        },        "rate": 20      }    ],    "billing_address": {      "name": "Tom Jones",      "company": "Tom Jones Hardware Ltd",      "address_line1": "7 Philosophy way",      "address_line2": null,      "city": "Willerby",      "region_code": null,      "postal_code": "BJ6 9MK",      "country_code": "GB",      "phone": "0123456789",      "sparklayer_id": "63428136-658f-48a6-beb7-7f333dfd9686",      "first_name": "Tom",      "last_name": "Jones"    },    "packages": [      {        "identifiers": {          "sparklayer_package_id": "63428136-658f-48a6-beb7-7f333dfd9686",          "platform": "123456789",          "internal": "<internal>",          "visible": "<visible>"        },        "accounting_files": [          {            "identifiers": {              "internal": "INV011",              "visible": "INV011"            },            "data": {              "uri": "https://example.com",              "type": "uri"            },            "file_type": "invoice"          }        ],        "line_items": [          {            "type": "custom",            "identifiers": {              "sparklayer_item_key": "<sparklayer_item_key>",              "sparklayer_variant_id": "45552423353839",              "sku": "CAT-MUG",              "platform": "123456789",              "internal": "<internal>",              "visible": "<visible>"            },            "name_parent": "T-Shirt",            "name_child": "Red",            "quantity": 4,            "custom_attributes": [              {                "key": "mug text",                "value": "best company ever"              }            ],            "line_total": {              "total_net": {                "number": "15.99",                "currency": "GBP"              },              "total_net_base": {                "number": "15.99",                "currency": "GBP"              },              "total_tax": {                "number": "15.99",                "currency": "GBP"              },              "total_tax_base": {                "number": "15.99",                "currency": "GBP"              },              "total_gross": {                "number": "15.99",                "currency": "GBP"              },              "total_gross_base": {                "number": "15.99",                "currency": "GBP"              },              "discount_net": {                "number": "15.99",                "currency": "GBP"              },              "discount_net_base": {                "number": "15.99",                "currency": "GBP"              },              "tax_rate": 20            },            "tax_lines": [              {                "title": "HST",                "amount": {                  "number": "15.99",                  "currency": "GBP"                },                "amount_base": {                  "number": "15.99",                  "currency": "GBP"                },                "rate": 20              }            ]          }        ],        "shipping_method": {          "sku": "SHIP-ECO",          "name": "Standard Shipping",          "line_total": {            "total_net": {              "number": "15.99",              "currency": "GBP"            },            "total_net_base": {              "number": "15.99",              "currency": "GBP"            },            "total_tax": {              "number": "15.99",              "currency": "GBP"            },            "total_tax_base": {              "number": "15.99",              "currency": "GBP"            },            "total_gross": {              "number": "15.99",              "currency": "GBP"            },            "total_gross_base": {              "number": "15.99",              "currency": "GBP"            },            "discount_net": {              "number": "15.99",              "currency": "GBP"            },            "discount_net_base": {              "number": "15.99",              "currency": "GBP"            },            "tax_rate": 20          },          "tax_lines": [            {              "title": "HST",              "amount": {                "number": "15.99",                "currency": "GBP"              },              "amount_base": {                "number": "15.99",                "currency": "GBP"              },              "rate": 20            }          ]        },        "shipping_address": {          "name": "Tom Jones",          "company": "Tom Jones Hardware Ltd",          "address_line1": "7 Philosophy way",          "address_line2": null,          "city": "Willerby",          "region_code": null,          "postal_code": "BJ6 9MK",          "country_code": "GB",          "phone": "0123456789",          "sparklayer_id": "63428136-658f-48a6-beb7-7f333dfd9686",          "first_name": "Tom",          "last_name": "Jones"        },        "shipments": [          {            "carrier": "Carrier Company Ltd",            "carrier_id": "<carrier_id>",            "tracking_url": "https://example.com"          }        ],        "type": "incoming"      }    ],    "accounting_files": [      {        "identifiers": {          "internal": "INV011",          "visible": "INV011"        },        "data": {          "uri": "https://example.com",          "type": "uri"        },        "file_type": "invoice"      }    ],    "custom_fields": [      {        "name": "delivery-date",        "value": "2023-10-28"      }    ],    "metadata": [      {        "name": "example-key",        "value": "1234"      }    ]  }'
{  "type": "order",  "purchase_identifiers": {    "sparklayer": "63428136-658f-48a6-beb7-7f333dfd9686",    "platform": "123456789",    "internal": "string",    "visible": "B2B01123"  },  "customer_identifiers": {    "sparklayer": "4217ba4f-7618-4e3b-b1af-9055639b18d1",    "sparklayer_impersonator": "4217ba4f-7618-4e3b-b1af-9055639b18d1",    "sparklayer_impersonator_assignee": "4217ba4f-7618-4e3b-b1af-9055639b18d1",    "sparklayer_child": "4217ba4f-7618-4e3b-b1af-9055639b18d1"  },  "company": {    "id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",    "section_id": "4217ba4f-7618-4e3b-b1af-9055639b18d1",    "section_name": "Bristol"  },  "payment_method": "quote",  "dates": {    "created_at": "2020-01-01T00:00:00+02:00",    "updated_at": "2020-01-01T00:00:00+02:00",    "placed_at": "2020-01-01T00:00:00+02:00",    "to_be_placed_at": "2020-01-01T00:00:00+02:00",    "calculated_submitted_at": "2020-01-01T00:00:00+02:00",    "expires_at": "2020-01-01T00:00:00+02:00",    "payment_due_at": "2020-01-01T00:00:00+02:00"  },  "customer_reference": "Please deliver to the back of the store",  "po_number": "PO-001",  "shipping_requested_date": "2020-01-01T00:00:00+02:00",  "recurring_purchase": {    "template_id": "0f8fad5b-d9cb-469f-a165-70867728950e",    "cancelled_at": "2020-01-01T00:00:00+02:00",    "to_be_placed_at_initial": "2020-01-01T00:00:00+02:00"  },  "currency_code": "GBP",  "currency_code_base": "GBP",  "calculated_shipping_address": "John Spark, SparkLayer, SparkLayer HQ, Example City, 12345",  "calculated_total": {    "number": "15.99",    "currency": "GBP"  },  "calculated_total_usd": {    "number": "15.99",    "currency": "GBP"  },  "calculated_total_base": {    "number": "15.99",    "currency": "GBP"  },  "calculated_fulfilment_status": "processing",  "quote": {    "status_slug": "string",    "status": {      "id": "string",      "name": "string",      "slug": "string",      "default": true,      "next": "string",      "actions": [        "edit_quote"      ],      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z",      "deleted_at": "2019-08-24T14:15:22Z"    },    "expiry": "2020-01-01T00:00:00+02:00"  },  "payment_status": "unpaid",  "total_paid": {    "number": "15.99",    "currency": "GBP"  },  "revision_date": "2020-01-01T00:00:00+02:00",  "tax_lines": [    {      "title": "HST",      "amount": {        "number": "15.99",        "currency": "GBP"      },      "amount_base": {        "number": "15.99",        "currency": "GBP"      },      "rate": 20    }  ],  "billing_address": {    "name": "Tom Jones",    "company": "Tom Jones Hardware Ltd",    "address_line1": "7 Philosophy way",    "address_line2": null,    "city": "Willerby",    "region_code": null,    "postal_code": "BJ6 9MK",    "country_code": "GB",    "phone": "0123456789",    "sparklayer_id": "63428136-658f-48a6-beb7-7f333dfd9686",    "first_name": "Tom",    "last_name": "Jones"  },  "packages": [    {      "identifiers": {        "sparklayer_package_id": "63428136-658f-48a6-beb7-7f333dfd9686",        "platform": "123456789",        "internal": "string",        "visible": "string"      },      "accounting_files": [        {          "identifiers": {            "internal": "INV011",            "visible": "INV011"          },          "data": {            "uri": "http://example.com",            "type": "uri"          },          "file_type": "invoice"        }      ],      "line_items": [        {          "type": "custom",          "identifiers": {            "sparklayer_item_key": "string",            "sparklayer_variant_id": "45552423353839",            "sku": "CAT-MUG",            "platform": "123456789",            "internal": "string",            "visible": "string"          },          "name_parent": "T-Shirt",          "name_child": "Red",          "quantity": 4,          "custom_attributes": [            {              "key": "mug text",              "value": "best company ever"            }          ],          "line_total": {            "total_net": {              "number": "15.99",              "currency": "GBP"            },            "total_net_base": {              "number": "15.99",              "currency": "GBP"            },            "total_tax": {              "number": "15.99",              "currency": "GBP"            },            "total_tax_base": {              "number": "15.99",              "currency": "GBP"            },            "total_gross": {              "number": "15.99",              "currency": "GBP"            },            "total_gross_base": {              "number": "15.99",              "currency": "GBP"            },            "discount_net": {              "number": "15.99",              "currency": "GBP"            },            "discount_net_base": {              "number": "15.99",              "currency": "GBP"            },            "tax_rate": 20          },          "tax_lines": [            {              "title": "HST",              "amount": {                "number": "15.99",                "currency": "GBP"              },              "amount_base": {                "number": "15.99",                "currency": "GBP"              },              "rate": 20            }          ]        }      ],      "shipping_method": {        "sku": "SHIP-ECO",        "name": "Standard Shipping",        "line_total": {          "total_net": {            "number": "15.99",            "currency": "GBP"          },          "total_net_base": {            "number": "15.99",            "currency": "GBP"          },          "total_tax": {            "number": "15.99",            "currency": "GBP"          },          "total_tax_base": {            "number": "15.99",            "currency": "GBP"          },          "total_gross": {            "number": "15.99",            "currency": "GBP"          },          "total_gross_base": {            "number": "15.99",            "currency": "GBP"          },          "discount_net": {            "number": "15.99",            "currency": "GBP"          },          "discount_net_base": {            "number": "15.99",            "currency": "GBP"          },          "tax_rate": 20        },        "tax_lines": [          {            "title": "HST",            "amount": {              "number": "15.99",              "currency": "GBP"            },            "amount_base": {              "number": "15.99",              "currency": "GBP"            },            "rate": 20          }        ]      },      "shipping_address": {        "name": "Tom Jones",        "company": "Tom Jones Hardware Ltd",        "address_line1": "7 Philosophy way",        "address_line2": null,        "city": "Willerby",        "region_code": null,        "postal_code": "BJ6 9MK",        "country_code": "GB",        "phone": "0123456789",        "sparklayer_id": "63428136-658f-48a6-beb7-7f333dfd9686",        "first_name": "Tom",        "last_name": "Jones"      },      "shipments": [        {          "carrier": "Carrier Company Ltd",          "carrier_id": "string",          "tracking_url": "http://example.com"        }      ],      "type": "incoming"    }  ],  "accounting_files": [    {      "identifiers": {        "internal": "INV011",        "visible": "INV011"      },      "data": {        "uri": "http://example.com",        "type": "uri"      },      "file_type": "invoice"    }  ],  "custom_fields": [    {      "name": "delivery-date",      "value": "2023-10-28"    }  ],  "metadata": [    {      "name": "example-key",      "value": "1234"    }  ]}

GETGet a purchase

Returns a purchase: a cart, quote, purchase awaiting approval or confirmation, or placed order. Set `lookupBy` to the `purchase_identifiers` field to match on (`sparklayer`, `platform`, `internal` or `visible`) and pass its value in `identifier`; with `sparklayer`, `identifier` must be a UUID. Returns `404` if no purchase matches.

DELDelete a purchase

Deletes the purchase that matches `lookupBy` and `identifier`, and returns `204`. Returns `404` if no purchase matches.