---
title: "Create cart"
method: POST
path: "/v1/carts"
tags: ["headless_carts"]
---

# Create cart

`POST /v1/carts`

## Query parameters

- `storefront_token` string, required
- `currency` 'USD' | 'EUR' | 'CAD' | 'GBP' | 'AUD' | 'NZD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'INR' | 'JPY' | 'MYR' | 'SGD' | 'MXN' | 'BRL' | 'CHF'

## Request body

- ComFourthwallAppHeadlessEndpointHeadlessCartXRequest
  - `items` ComFourthwallAppHeadlessEndpointHeadlessCartRequestItem[], required
    - `variantId` string, uuid, required
    - `quantity` integer, 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.

## Response `200`

OK

- ComFourthwallAppHeadlessModelCartV1
  - `id` string, required
  - `items` ComFourthwallAppHeadlessModelCartV1CartItemV1[], required
    - `variant` ComFourthwallAppHeadlessModelCartProductVariantV1, required
      - `id` string, required
      - `name` string, required
      - `sku` string, required
      - `unitPrice` Money, required
        - `value` number, required
        - `currency` string, required
      - `compareAtPrice` Money
        - `value` number, required
        - `currency` string, required
      - `attributes` ComFourthwallOpenapiModelOfferAbstractV1OfferVariantAbstractV1Attributes, required
        - `description` string, required
        - `color` ComFourthwallOpenapiModelOfferAbstractV1OfferVariantAbstractV1AttributesColor
          - `name` string, required
          - `swatch` string, required
        - `size` ComFourthwallOpenapiModelOfferAbstractV1OfferVariantAbstractV1AttributesSize
          - `name` string, required
      - `stock` union, required
        - ComFourthwallOpenapiModelOfferAbstractV1OfferVariantAbstractV1StockLimited
          - `type` 'LIMITED', required
          - `inStock` integer, required
        - ComFourthwallOpenapiModelOfferAbstractV1OfferVariantAbstractV1StockUnlimited
          - `type` 'UNLIMITED', required
      - `weight` ComFourthwallOpenapiModelOfferAbstractV1OfferVariantAbstractV1Weight, required
        - `value` number, required
        - `unit` string, required
      - `dimensions` ComFourthwallOpenapiModelOfferAbstractV1OfferVariantAbstractV1Dimensions, required
        - `length` number, required
        - `width` number, required
        - `height` number, required
        - `unit` string, required
      - `images` ComFourthwallOpenapiModelImage[], required
        - `id` string, required
        - `url` string, required
        - `width` integer, required — The original width of the image in pixels.
        - `height` integer, required — The original height of the image in pixels.
        - `transformedUrl` string, required — Transformed URL with applied image processing (e.g., resizing, optimization)
      - `product` ComFourthwallAppHeadlessModelProductStubV1, required
        - `id` string, required
        - `name` string, required
        - `slug` string, required
    - `quantity` integer, required
    - `groupedBy` ComFourthwallAppHeadlessModelCartItemGroupedByV1Bundle
      - `type` string, required
      - `bundleId` string, required
      - `groupedId` string, required
  - `metadata` object

## Other responses

- `400` — Possible errors: `CART_DUPLICATE_VARIANT_IDS_ERROR`, `CART_FORBIDDEN_MEMBERS_ONLY_OFFERS_ERROR`, `CART_INCOMPLETE_BUNDLE_ERROR`, `CART_ITEM_NOT_FOUND_FOR_SHOP_ERROR`, `CART_OFFER_NOT_AVAILABLE`, `CART_OFFER_NOT_PURCHASABLE_ERROR`, `CART_PROMOTION_REQUIREMENTS_NOT_MET`, `CART_QUANTITY_TOO_HIGH`, `CHECKOUT_PROMOTION_ALREADY_USED_BY_CUSTOMER`, `CHECKOUT_PROMOTION_AVAILABLE_ONLY_FOR_SIGNED_CUSTOMERS`, `CHECKOUT_PROMOTION_FREE_SHIPPING_COUNTRY_NOT_SUPPORTED`, `CHECKOUT_PROMOTION_MAXIMUM_USES_LIMIT_EXCEEDED`, `CHECKOUT_PROMOTION_NOT_ALLOWED_FOR_CUSTOMER_TIER`, `CHECKOUT_PROMOTION_NOT_ALLOWED_FOR_CUSTOMER_TWITCH_TIER`, `CHECKOUT_PROMOTION_NOT_ALLOWED_FOR_GIVEN_ITEMS`, `PROMOTION_ALREADY_USED_BY_CUSTOMER`, `PROMOTION_AVAILABLE_ONLY_FOR_SIGNED_CUSTOMERS`, `PROMOTION_FREE_SHIPPING_COUNTRY_NOT_SUPPORTED`, `PROMOTION_MAXIMUM_USES_LIMIT_EXCEEDED`, `PROMOTION_MISSING_REQUIRED_PRODUCTS`, `PROMOTION_NOT_ALLOWED_FOR_CUSTOMER_TIER`, `PROMOTION_NOT_ALLOWED_FOR_CUSTOMER_TWITCH_TIER`, `PROMOTION_NOT_ALLOWED_FOR_GIVEN_ITEMS`, `VARIANT_NOT_ALLOWED_FOR_FREE_PRODUCTS`
- `404` — Possible errors: `CART_NOT_FOUND`, `CART_OFFER_NOT_FOUND`, `CHECKOUT_PROMOTION_CODE_DO_NOT_EXISTS`, `OFFER_VARIANT_NOT_FOUND_ERROR`, `SHOP_TEAM_MEMBER_SHOP_NOT_FOUND_ERROR`
- `409` — Possible errors: `CHECKOUT_PROMOTION_REQUIRE_MINIMUM_ORDER_VALUE`, `PROMOTION_REQUIRE_MINIMUM_ORDER_VALUE`

---

[API](https://skmtc.dev/fourthwall/apis/fourthwall-apis.md) · [All operations](https://skmtc.dev/fourthwall/apis/fourthwall-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fourthwall/fourthwall-apis/revisions/f85ba94932b7/schema)