Skip to main content

​
Overview

The createCart mutation initializes a new shopping cart for a customer. This is the first step in the checkout flow and must be called before adding items to the cart.

​
GraphQL Mutation

mutation CreateCart($data: CartCreateInput!) {
  createCart(data: $data) {
    id
    email
    type
    region {
      id
      name
      currency {
        code
      }
    }
    lineItems {
      id
      quantity
    }
  }
}

​
Parameters

​
data
CartCreateInput
required
The cart data object

​
Response

​
id
string
Unique identifier for the created cart
​
email
string
Customer’s email address
​
type
string
Cart type (default, swap, draft_order, etc.)
​
region
object
The region associated with this cart
​
lineItems
array
Array of line items in the cart (empty at creation)
​
shippingMethods
array
Array of shipping methods (automatically populated with cheapest option for the region)

​
Example Request

const { createCart } = await openfrontClient.request(
  gql`
    mutation CreateCart($data: CartCreateInput!) {
      createCart(data: $data) {
        id
        region {
          id
          name
          currency {
            code
          }
        }
      }
    }
  `,
  {
    data: {
      region: { 
        connect: { id: "clx123abc456" } 
      }
    }
  }
);

console.log(createCart.id); // Cart ID for subsequent operations

​
Behavior

​
Automatic User Association

If a user is authenticated when creating a cart, the cart is automatically associated with that user’s account.

​
Automatic Shipping Method

When a cart is created with a region, the system automatically:
  1. Finds the cheapest shipping option for that region
  2. Creates a shipping method record
  3. Associates it with the cart
This ensures customers always have a default shipping option selected.

​
Region Requirements

The region parameter is required because it determines:
  • Currency for all prices
  • Tax rates to apply
  • Available shipping options
  • Available payment providers

​
Next Steps

After creating a cart:
  1. Add items to the cart
  2. Set shipping and billing addresses
  3. Select shipping method (or use the default)
  4. Create payment sessions
  5. Complete the cart to create an order

Build docs developers (and LLMs) love

Get started for freeTalk to us