Skip to content
API referenceCustomers API

List shopping lists

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.
  • 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.
Build with AI: ready-made prompts and MCP setup
GET
/api/v2/customers/{lookupBy}/{identifier}/shopping-lists

Returns the customer's shopping lists. With section_id, returns that company location's lists and the customer's own lists that don't belong to a location.

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

What identifier is: sparklayer (the customer's SparkLayer ID), platform (their ID on your eCommerce platform) or email (their email address).

Value in

  • "sparklayer"
  • "platform"
  • "email"
identifier*string

The customer's ID or email address, of the kind set by lookupBy. SparkLayer IDs are UUIDs; legacy cu_ IDs work too, except for shopping lists and favourites. Email lookups are exact and case-sensitive: URL-encode the address, with + as %2B.

Query Parameters

section_id?string

Scope to an active company section the customer belongs to or administers; any other section returns 400. Omit for merchants that do not use company sections.

Formatuuid

Header Parameters

Site-Id*string

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

Length1 <= length

Response Body

application/json

application/problem+json

curl -X GET "https://app.sparklayer.io/api/v2/customers/platform/7843024560291/shopping-lists" \  -H "Authorization: Bearer <ACCESS_TOKEN>" \  -H "Site-Id: jones-climbing"
[  {    "id": "6502579c-90b9-4fc1-8e78-083cb84702d8",    "created_at": "2003-05-20T08:20:00Z",    "updated_at": "2003-05-21T08:20:00Z",    "name": "Weekly list",    "contents": [      {        "sku": "TEST",        "quantity": 9      }    ],    "company": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "section_id": "f5e5c4dc-7d2e-40f1-a895-9bb2f8703fd8",      "section_name": "string"    }  }]

POSTAdjust a customer's account balance

Adds an entry to the customer's account credit ledger, which makes up the balance shown in [My Account](/help/storefront/interfaces/my-account) when you use [pay on account](/help/ordering/credit-net-terms-and-invoicing), and returns `201`. A positive `amount` increases what the customer owes, and a negative one reduces it. What it means depends on `type`: - **`order`** and **`transaction`**: an amount to add, such as an order total or a payment (negative). - **`opening_balance`**: the balance on `date`. From then on, the balance is this amount plus the `order` and `transaction` entries dated on or after `date`. Earlier entries, and `default` entries, stop counting. - **`default`**: the balance you want now. SparkLayer records the difference from the current balance. Once the customer has an opening balance, `default` entries don't change it. Always send `date`: without it, the entry is dated 1 January 0001. The Purchasing API already adds an `order` entry for each order you send, and a `transaction` entry for each purchase transaction with `apply_to_balance`. Don't add them again here.

POSTCreate a shopping list

Creates a shopping list for the customer and returns it with `201`. Quantities are whole numbers up to 1,000. To share the list with a company location, set `company.section_id`: it can't be changed afterwards.