headless_carts

Add to cart

post/v1/carts/{cartId}/add

Path parameters

cartIdstring required

Query parameters

storefront_tokenstring required

Example:ptkn_xxxxxxxxxxxxxxxxxx

currency'USD' | 'EUR' | 'CAD' | 'GBP' | 'AUD' | 'NZD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'INR' | 'JPY' | 'MYR' | 'SGD' | 'MXN' | 'BRL' | 'CHF'

Request body

metadataobject

Custom metadata key-value pairs. Max 10 keys, keys must be alphanumeric with underscores, max 256 chars per key, max 512 bytes per value, max 2KB total.

Example request

{
  "items": [
    {
      "variantId": "000009c2-0c75-0024-0000-09c20c750024",
      "quantity": 1,
      "bundleId": "000009c2-0c75-0024-0000-09c20c750024"
    }
  ],
  "metadata": {
    "asset_id": "abc123",
    "campaign": "summer_2026"
  }
}

Response

idstring required

metadataobject

Example response

{
  "items": [
    {
      "variant": {
        "unitPrice": {
          "value": 10,
          "currency": "USD"
        },
        "compareAtPrice": {
          "value": 10,
          "currency": "USD"
        },
        "attributes": {
          "description": "Black, L",
          "color": {
            "name": "Black",
            "swatch": "#000000"
          },
          "size": {
            "name": "L"
          }
        },
        "stock": {
          "inStock": 5
        },
        "weight": {
          "value": 1,
          "unit": "kg"
        },
        "dimensions": {
          "length": 1,
          "width": 2,
          "height": 3,
          "unit": "cm"
        },
        "images": [
          {
            "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
            "url": "https://fourthwall.com/image.png",
            "width": 800,
            "height": 600,
            "transformedUrl": "https://fourthwall.com/image.png"
          }
        ]
      }
    }
  ]
}

Changes

Changed in 1 of the 2 revisions of this API.123

Sep 1, 2026c31b4d6c63bc123See the full diff
- ▲
  the // request property's max was decreased to 1000.00
  request-property-max-decreased
- ●
  removed the request property //
  request-property-removed
- ●
  removed the request property //
  request-property-removed
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property
  new-optional-request-property
- ○
  the // request property's min was decreased from 1.00 to 0.00
  request-property-min-decreased
This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history