---
title: "Create a cart"
method: POST
path: "/open-api/v1.0/carts"
tags: ["Carts"]
---

# Create a cart

`POST /open-api/v1.0/carts`

*Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).*

Creates a new cart with the specified items

## Request body

- ComFourthwallOpenapiModelCreateCartRequestV1
  - `items` ComFourthwallOpenapiModelCartItemRequestV1[], required
    - `variantId` string, 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 `201`

Created

- ComFourthwallOpenapiModelCartV1
  - `id` string, required
  - `items` ComFourthwallOpenapiModelCartV1CartItemV1[], required
    - `variant` ComFourthwallOpenapiModelCartVariantV1, 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` ComFourthwallOpenapiModelCartProductV1, required
        - `id` string, required
        - `name` string, required
        - `slug` string, required
    - `quantity` integer, required
  - `metadata` object — Custom metadata key-value pairs.

## 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`
- `429` — Rate limited: 100 requests / 10 seconds per shop.

---

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