> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Alias of POST /api/cart/add

> For an existing protected thread, send its x-widget-thread-token capability in addition to widget identity…

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`

**variantId** `string` *required*

Shopify variant id (numeric or GID).

**quantity** `integer`

Default: `1`. Minimum: `1`.

**sessionId** `string`

Widget session id used to reuse the visitor's cart.

**discountCode** `string`

Applied only when the server issued it for `threadId` (see route description).

**threadId** `string`

**threadToken** `string`

### Response

`CartAddResponse`

**ok** `boolean` *required*

Fixed value: `true`.

**success** `boolean` *required*

Fixed value: `true`.

**variantId** `string` *required*

**quantity** `integer` *required*

**cartId** `string` *required*

**cartItemCount** `integer` *required*

**subtotal** `string,number,null`

**total** `string,number,null`

**checkoutUrl** `string (uri)` *required*

**discountApplied** `boolean` *required*

**discountError** `string`

**discountIgnored** `boolean`

Fixed value: `true`.

### 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](https://docs.stateset.com/spec/chat-widget.json) for declared schemas and alternatives.
This page also includes documented corrections from the [spec overlays](https://github.com/stateset/docs/tree/main/spec/overlays).
Example IDs and values are illustrative; replace them with records from your workspace.

```bash cURL theme={null}
curl --silent --show-error --fail-with-body --request POST \
  --url 'https://api.example.com/api/shopify/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"
}'
```

```json 200 theme={null}
{
  "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
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.