Skip to content
API referenceOrdering API

Update a cart

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
PATCH
/api/v1/carts/{id}

Updates the cart and returns it along with a result for each line item. Line items are always replaced: quantities are absolute, and omitting line_items or sending an empty array empties the cart. custom_fields also replaces the existing set, temporary_shipping_address takes precedence over shipping_address_id, and an empty string clears customer_reference, po_number or shipping_requested_date.

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

id*string

The cart's ID: the cart_id returned by Create a cart.

Header Parameters

Site-Id*string

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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

line_items?array<>

Replaces all existing cart line items. The provided quantities are absolute values (not deltas). Passing an empty array clears the cart.

shipping_address_id?string|null
temporary_shipping_address?|null
customer_reference?string|null
po_number?string|null
shipping_requested_date?string|null
custom_fields?array<>

Replaces all existing custom fields on the cart. Any existing field not included is removed. Passing an empty array clears all custom fields.

Response Body

application/json

application/json

application/problem+json

curl -X PATCH "https://app.sparklayer.io/api/v1/carts/9151f21f-43ae-43b4-92f3-f4af67cdf544" \  -H "Authorization: Bearer <ACCESS_TOKEN>" \  -H "Site-Id: jones-climbing" \  -H "Content-Type: application/json" \  -d '{    "line_items": [      {        "sku": "<sku>",        "quantity": 0      }    ],    "shipping_address_id": "<shipping_address_id>",    "temporary_shipping_address": {      "first_name": "<first_name>",      "last_name": "<last_name>",      "company": "<company>",      "address_line1": "<address_line1>",      "address_line2": "<address_line2>",      "city": "<city>",      "region_code": "<region_code>",      "postal_code": "<postal_code>",      "country_code": "<country_code>",      "phone": "<phone>"    },    "customer_reference": "<customer_reference>",    "po_number": "<po_number>",    "shipping_requested_date": "<shipping_requested_date>",    "custom_fields": [      {        "name": "<name>",        "value": "<value>"      }    ]  }'
{  "cart": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "intent": "ORDER",    "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",    "shipping_address_id": "cfb5f13a-388c-401e-be3f-ff8f3abcd015",    "billing_address_id": "8e8c171a-db37-4819-9621-58c64d04ab7d",    "items": [      {        "sku": "string",        "quantity": 0,        "line_total": {          "net": "string",          "gross": "string",          "tax_rate": 0,          "currency_code": "string",          "tax_inclusive_display": false        },        "unit_total": {          "net": "string",          "gross": "string",          "tax_rate": 0,          "currency_code": "string",          "tax_inclusive_display": false        }      }    ],    "totals": {      "total": {        "pre_discount": {          "net": {            "amount": "string",            "currency_code": "string"          },          "gross": {            "amount": "string",            "currency_code": "string"          },          "tax": {            "amount": "string",            "currency_code": "string"          },          "apportioned_tax_rate": 0.1,          "currency": "string"        },        "discount": {          "net": {            "amount": "string",            "currency_code": "string"          },          "gross": {            "amount": "string",            "currency_code": "string"          },          "tax": {            "amount": "string",            "currency_code": "string"          },          "apportioned_tax_rate": 0.1,          "currency": "string"        },        "charge": {          "net": {            "amount": "string",            "currency_code": "string"          },          "gross": {            "amount": "string",            "currency_code": "string"          },          "tax": {            "amount": "string",            "currency_code": "string"          },          "apportioned_tax_rate": 0.1,          "currency": "string"        }      },      "shipping": {        "pre_discount": {          "net": {            "amount": "string",            "currency_code": "string"          },          "gross": {            "amount": "string",            "currency_code": "string"          },          "tax": {            "amount": "string",            "currency_code": "string"          },          "apportioned_tax_rate": 0.1,          "currency": "string"        },        "discount": {          "net": {            "amount": "string",            "currency_code": "string"          },          "gross": {            "amount": "string",            "currency_code": "string"          },          "tax": {            "amount": "string",            "currency_code": "string"          },          "apportioned_tax_rate": 0.1,          "currency": "string"        },        "charge": {          "net": {            "amount": "string",            "currency_code": "string"          },          "gross": {            "amount": "string",            "currency_code": "string"          },          "tax": {            "amount": "string",            "currency_code": "string"          },          "apportioned_tax_rate": 0.1,          "currency": "string"        }      },      "sub_total": {        "pre_discount": {          "net": {            "amount": "string",            "currency_code": "string"          },          "gross": {            "amount": "string",            "currency_code": "string"          },          "tax": {            "amount": "string",            "currency_code": "string"          },          "apportioned_tax_rate": 0.1,          "currency": "string"        },        "discount": {          "net": {            "amount": "string",            "currency_code": "string"          },          "gross": {            "amount": "string",            "currency_code": "string"          },          "tax": {            "amount": "string",            "currency_code": "string"          },          "apportioned_tax_rate": 0.1,          "currency": "string"        },        "charge": {          "net": {            "amount": "string",            "currency_code": "string"          },          "gross": {            "amount": "string",            "currency_code": "string"          },          "tax": {            "amount": "string",            "currency_code": "string"          },          "apportioned_tax_rate": 0.1,          "currency": "string"        }      }    },    "customer_addresses": [      {        "id": "string",        "uuid": "string",        "first_name": "string",        "last_name": "string",        "company": "string",        "description": "string",        "address_line_1": "string",        "address_line_2": "string",        "city": "string",        "postal_code": "string",        "country_code": "string",        "region_code": "string",        "phone": "string",        "external_id": "string"      }    ],    "shipping_rate_handle": "string",    "payment_method": "string",    "validation_errors": [      {        "overridden": true,        "type": "maximum-order-item-quantity",        "maximum": 0      }    ],    "customer_reference": "string",    "po_number": "string",    "shipping_requested_date": "string",    "custom_fields": [      {        "name": "string",        "value": "string"      }    ]  },  "item_update_results": [    {      "sku": "string",      "name": "string",      "requested_quantity": 0,      "resultant_quantity": 0,      "messages": [        {          "type": "cannot-adjust-overridden-qty"        }      ]    }  ]}

DELDelete a cart

Deletes a cart and returns `204`. The request succeeds even if the cart doesn't exist, so it's safe to retry.

POSTComplete a cart

Places the order: checks the shipping rate and payment method, creates a purchase, deletes the cart and returns the new `purchase_id` with a `201`. If the cart has validation errors you haven't listed in `ignore_validation_errors` (use `"*"` to ignore all of them), you get a `422` (`cart-validation-errors`) and no order is created. Because the cart is deleted once the order is placed, repeating the call returns `404`.