> ## 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.

# Add a variant to the cart (optional)

> For headless or cross-domain installs: proxies a Shopify Storefront cart mutation and returns checkoutUrl…

For headless or cross-domain installs: proxies a Shopify Storefront cart mutation and returns `checkoutUrl`. Not needed when `cartMode: 'shopify_ajax'` lets the widget call Shopify's `/cart/add.js` directly.

### Request body

`CartAdd`

<ParamField body="variantId" type="string" required>
  e.g. `gid://shopify/ProductVariant/123`
</ParamField>

<ParamField body="quantity" type="number" required />

<ParamField body="sessionId" type="string" />

### Response

`CartAddResponse`

<ResponseField name="checkoutUrl" type="string" />

### Status codes

| Code  | Meaning |
| ----- | ------- |
| `200` | OK      |
| `400` | Error   |
| `401` | Error   |

<RequestExample>
  ```bash cURL theme={null}
  curl --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": 2,
    "sessionId": "string"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "checkoutUrl": "string"
  }
  ```
</ResponseExample>