Skip to main content
POST
/
v1
/
carts
Create cart
curl --request POST \
  --url https://storefront-api.fourthwall.com/v1/carts \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "variantId": "000009c2-0c75-0024-0000-09c20c750024",
      "quantity": 1
    }
  ],
  "metadata": {
    "asset_id": "abc123",
    "campaign": "summer_2026"
  }
}
'
{ "id": "<string>", "items": [ { "variant": { "id": "<string>", "name": "<string>", "sku": "<string>", "unitPrice": { "value": 10, "currency": "USD" }, "attributes": { "description": "Black, L", "color": { "name": "Black", "swatch": "#000000" }, "size": { "name": "L" } }, "stock": { "type": "<string>", "inStock": 5 }, "weight": { "value": "1.0", "unit": "kg" }, "dimensions": { "length": "1.0", "width": "2.0", "height": "3.0", "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" } ], "product": { "id": "<string>", "name": "<string>", "slug": "<string>" }, "compareAtPrice": { "value": 10, "currency": "USD" } }, "quantity": 123, "groupedBy": { "type": "<string>", "bundleId": "<string>", "groupedId": "<string>" } } ], "metadata": {} }

Query Parameters

​
storefront_token
string
required
Example:

"ptkn_xxxxxxxxxxxxxxxxxx"

​
currency
enum<string>
Available options:
USD,
EUR,
CAD,
GBP,
AUD,
NZD,
SEK,
NOK,
DKK,
PLN,
INR,
JPY,
MYR,
SGD,
MXN,
BRL

Body

application/json
​
items
Request Item · object[]
required
​
metadata
object

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:
{
  "asset_id": "abc123",
  "campaign": "summer_2026"
}

Response

OK

​
id
string
required
​
items
Cart Item · object[]
required
​
metadata
object