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,
          "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"
          }
        ],
        "product": {
          "id": "<string>",
          "name": "<string>",
          "slug": "<string>"
        },
        "compareAtPrice": {
          "value": 10,
          "currency": "USD"
        }
      },
      "quantity": 123,
      "groupedBy": {
        "type": "<string>",
        "bundleId": "<string>",
        "groupedId": "<string>"
      }
    }
  ],
  "metadata": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.fourthwall.com/llms.txt

Use this file to discover all available pages before exploring further.

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,
CHF

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