curl --silent --show-error --fail-with-body --request POST \
--url 'https://api.example.com/api/cart/add' \
--header 'x-widget-token: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"variantId": "string",
"quantity": 1,
"sessionId": "string",
"discountCode": "5.00",
"threadId": "string",
"threadToken": "YOUR_API_KEY"
}'
{
"ok": true,
"success": true,
"variantId": "string",
"quantity": 2,
"cartId": "string",
"cartItemCount": 1,
"subtotal": "98.00",
"total": "102.12",
"checkoutUrl": "https://example.com/webhooks/stateset",
"discountApplied": true,
"discountError": "5.00",
"discountIgnored": true
}
Add a variant to a Shopify cart
discountCode is applied only when the server issued it for this request’s thread (the YSE first-purchase code on a thread whose eligibility check passed…
POST
/
api
/
cart
/
add
curl --silent --show-error --fail-with-body --request POST \
--url 'https://api.example.com/api/cart/add' \
--header 'x-widget-token: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"variantId": "string",
"quantity": 1,
"sessionId": "string",
"discountCode": "5.00",
"threadId": "string",
"threadToken": "YOUR_API_KEY"
}'
{
"ok": true,
"success": true,
"variantId": "string",
"quantity": 2,
"cartId": "string",
"cartItemCount": 1,
"subtotal": "98.00",
"total": "102.12",
"checkoutUrl": "https://example.com/webhooks/stateset",
"discountApplied": true,
"discountError": "5.00",
"discountIgnored": true
}
discountCode is applied only when the server issued it for this request’s thread
(the YSE first-purchase code on a thread whose eligibility check passed; the thread
token is enforced like the thread routes). Any other code is dropped and
discountIgnored: true is added to the response.
For an existing protected thread, send its x-widget-thread-token capability in addition to widget identity. Widget identity is verified when signing is configured; tokenless compatibility does not establish tenant ownership. See the authentication and recovery guide for credential and retry rules.
Request body
CartAddRequest
Response
CartAddResponse
Status codes
| Code | Meaning |
|---|---|
200 | Line added to the Shopify cart |
400 | Shopify not configured, missing variant, or Shopify user error |
401 | Widget token missing, malformed, expired, from the future, or badly signed |
403 | Request org/agent disagrees with the widget token claims |
429 | Too many requests for this IP (scoped by verified org/agent) |
500 | Unhandled error |
Using this contract
Read the source OpenAPI document for declared schemas and alternatives. This page also includes documented corrections from the spec overlays. Example IDs and values are illustrative; replace them with records from your workspace.curl --silent --show-error --fail-with-body --request POST \
--url 'https://api.example.com/api/cart/add' \
--header 'x-widget-token: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"variantId": "string",
"quantity": 1,
"sessionId": "string",
"discountCode": "5.00",
"threadId": "string",
"threadToken": "YOUR_API_KEY"
}'
{
"ok": true,
"success": true,
"variantId": "string",
"quantity": 2,
"cartId": "string",
"cartItemCount": 1,
"subtotal": "98.00",
"total": "102.12",
"checkoutUrl": "https://example.com/webhooks/stateset",
"discountApplied": true,
"discountError": "5.00",
"discountIgnored": true
}
Last modified on November 13, 2026