Create a cart and go to checkout#

This guide walks through the complete cart-to-checkout flow: creating a cart, adding products, setting a shipping address and method, then confirming the cart to receive an order with a checkout URL.

Overview#

Create an empty cart with createCart
Add products by SKU with addItemsToCart
Set a shipping address with addShippingAddressToCart
Choose a shipping method with addShippingMethodToCart
Verify the cart is valid, then confirm it with confirmCart
Redirect the customer to the checkout URL

Step 1 — Create a cart#

createCart takes no input.

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

mutation {
  createCart {
    cart {
      id
      number
      currency
    }
  }
}

Save the returned cart.id — you'll pass it as cart_id in every subsequent mutation.

ℹ

Tip:Pass channel_id if you operate multiple storefronts. Pass country_code to pre-set the delivery country and ensure correct tax calculation from the start.

Step 2 — Add items#

Input: AddItemsToCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	ID of the cart returned in step 1.
`items`	[ItemInput!]!▾	Required	Items to add.

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

mutation AddItems($input: AddItemsToCartInput!) {
  addItemsToCart(input: $input) {
    cart {
      id
      items {
        sku
        label
        quantity
        total
      }
      subtotal
      total
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "items": [
      { "sku": "BLK-HOODIE-M", "quantity": 1 },
      { "sku": "BLK-HOODIE-L", "quantity": 2 }
    ]
  }
}

Step 3 — Set a shipping address#

Input: AddShippingAddressToCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	ID of the cart.
`address`	AddressInput!▾	Required	Delivery address.

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

mutation AddShippingAddress($input: AddShippingAddressToCartInput!) {
  addShippingAddressToCart(input: $input) {
    cart {
      id
      delivery {
        address {
          address_line_1
          locality
          postal_code
          country_code
        }
      }
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "address": {
      "address_line_1": "Keizersgracht 313",
      "locality": "Amsterdam",
      "postal_code": "1016 EE",
      "country_code": "NL"
    }
  }
}

Step 4 — Choose a shipping method#

First, query the available shipping methods for your channel:

query GetShippingMethods($first: Int) {
  shippingMethods(first: $first) {
    methods {
      id
      name
      carrier
    }
  }
}

{ "first": 10 }

Then apply one to the cart:

Input: AddShippingMethodToCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	ID of the cart.
`method_id`	String!	Required	ID of the shipping method to apply.

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

mutation AddShippingMethod($input: AddShippingMethodToCartInput!) {
  addShippingMethodToCart(input: $input) {
    cart {
      id
      delivery {
        method {
          id
          name
        }
      }
      total
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "method_id": "e5f6a7b8-c9d0-1234-5678-90abcdef0123"
  }
}

Step 5 — Verify and confirm#

Before confirming, check that the cart has no validation errors:

query CheckCart($id: String!) {
  cart(id: $id) {
    id
    total
    validation_errors {
      code
      message
    }
    checkout {
      url
    }
  }
}

{ "id": "72fca344-2a6f-4c3e-b4ca-029920b2522a" }

Once valid, confirm the cart to convert it into an order:

Input: ConfirmCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	ID of the cart to confirm.

Returns: Order

Name	Type	Required	Description
`id`	ID!	Required	The ID
`number`	String!	Required	Order number
`total`	Money!	Required	Total value
`currency`	Currency!	Required	Currency code

mutation ConfirmCart($input: ConfirmCartInput!) {
  confirmCart(input: $input) {
    order {
      id
      number
      total
      checkout {
        url
      }
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a"
  }
}

Redirect the customer to order.checkout.url to complete payment.

Notes#

confirmCart fails if cart.validation_errors is non-empty — ensure items, shipping address, and shipping method are all set.
Money values (total, subtotal) are integers in cents — e.g. 2499 means € 24,99.
To add a billing address before confirming, use addBillingAddressToCart with the same AddressInput shape.
To add a payment method before confirming, use addPaymentMethodToCart with method_id and the required issuer_id.
See Authentication for how to pass your API key.