Checkout

The recommended GraphQL checkout against a single cart is an 8-step sequence. Each step links to its dedicated card below.

1. createGuestCart — Create a guest cart (or fetch customerCart { id } for authenticated flows).
2. addProductsToCart — Add line items to the cart.
3. setGuestEmailOnCart — Attach a contact email (guest only; customer token carries the email implicitly).
4. setShippingAddressesOnCart — Set the shipping destination, or a pickup location code.
5. setBillingAddressOnCart — Set the billing address (or mirror the shipping address).
6. setShippingMethodsOnCart — Choose a carrier and method for each shipping address.
7. setPaymentMethodOnCart — Pick the payment method (offline or gateway).
8. placeOrder — Place the order and read orderV2 { number token } from the response.

Query for available methods

{
    cart(cart_id: "cart-id") {
        available_payment_methods { code title }
        shipping_addresses {
            available_shipping_methods {
                carrier_code method_code
                amount { value currency }
                price_incl_tax { value }
            }
        }
        prices {
            grand_total { value currency }
            subtotal_excluding_tax { value }
            applied_taxes { amount { value } label }
        }
    }
}

Initializes a new shopping cart for either guest users or authenticated customers. The system can auto-generate a unique cart identifier, or you may pass a custom 32-character identifier via cart_id.

When working with registered customers, the request must include the customer authorization header. The returned value is the quote id used by every subsequent cart mutation.

mutation {
    createEmptyCart(
        input: { cart_id: "x2345678901234567890123456789012" }
    )
}

Input field cart_id (String, optional) — custom 32-char identifier. Omit to let Commerce generate one.

Creates an empty cart dedicated to guest shoppers. The mutation accepts an optional cart_uid (32 characters) when the merchant wants to control the id; otherwise Commerce generates it.

Unlike createEmptyCart, the response is the Cart object, so you can use the returned cart.id directly in follow-up calls.

mutation {
    createGuestCart(input: { cart_uid: "x2345678901234567890123456789012" }) {
        cart { id }
    }
}

Input field cart_uid (String, optional) — custom 32-char cart identifier.

Adds multiple product types to a cart in a single GraphQL operation. Replaces the per-type mutations (addSimpleProductsToCart, addConfigurableProductsToCart, etc.).

Each CartItemInput carries a SKU and quantity. Use selected_options (dropdowns, radios, swatches) for predefined choices and entered_options (text fields, file uploads, gift card values) for shopper-provided inputs. Option uids come from the product schema.

mutation {
    addProductsToCart(
        cartId: "8k0Q4MpH2IGahWrTRtqM61YV2MtLPApz"
        cartItems: [{ quantity: 1, sku: "24-MB04" }]
    ) {
        cart {
            itemsV2 {
                items { product { name sku } quantity }
            }
        }
        user_errors { code message }
    }
}

The response always includes user_errors; always check it — an operation can partially succeed (some items added, others rejected).

Guest checkouts require a contact email to be attached to the cart before placeOrder succeeds. Authenticated customers skip this step — their email comes from the customer token.

The mutation validates both the cart existence and the email format before associating them.

mutation {
    setGuestEmailOnCart(
        input: {
            cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C"
            email: "jdoe@example.com"
        }
    ) {
        cart { email }
    }
}

Sets one or more shipping addresses on a specific cart. You can pass a full address object, reference an existing customer_address_id, or — for in-store collection — provide a pickup_location_code.

The step is unnecessary when the cart contains only digital products, or when the billing address has same_as_shipping: true.

mutation {
    setShippingAddressesOnCart(
        input: {
            cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C"
            shipping_addresses: [{
                address: {
                    firstname: "Bob"
                    lastname: "Roll"
                    street: ["Magento Pkwy"]
                    city: "Austin"
                    region: "TX"
                    postcode: "78758"
                    country_code: "US"
                    telephone: "8675309"
                }
                pickup_location_code: "txspeqs"
            }]
        }
    ) {
        cart {
            shipping_addresses {
                firstname lastname city country { code }
            }
        }
    }
}

Assigns billing address information to the cart. Three modes: full address object, reference to a saved customer_address_id, or same_as_shipping: true to mirror the shipping address.

Passing both address and customer_address_id is a conflict and will error. When same_as_shipping is true, Commerce synchronizes the billing location with the shipping destination automatically.

mutation {
    setBillingAddressOnCart(
        input: {
            cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C"
            billing_address: {
                address: {
                    firstname: "Bob" lastname: "Roll"
                    street: ["Magento Pkwy", "Main Street"]
                    city: "Austin" region: "TX" postcode: "78758"
                    country_code: "US" telephone: "8675309"
                    save_in_address_book: true
                }
                same_as_shipping: false
            }
        }
    ) {
        cart {
            billing_address {
                firstname lastname street city
                region { code label } postcode
                country { code label }
            }
        }
    }
}

Applies one or more delivery methods to the cart. Each entry carries a carrier_code + method_code; Commerce validates that the method is applicable to the cart\'s shipping address.

In-store pickup: do not use this mutation. Instead, set the pickup_location_code on the shipping address via setShippingAddressesOnCart.

mutation {
    setShippingMethodsOnCart(
        input: {
            cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG"
            shipping_methods: [
                { carrier_code: "tablerate", method_code: "bestway" }
            ]
        }
    ) {
        cart {
            shipping_addresses {
                selected_shipping_method {
                    carrier_code carrier_title
                    method_code method_title
                    amount { value currency }
                }
            }
        }
    }
}

Applies a payment method to the cart. Supports offline methods (bank transfer, cash on delivery) and online gateways (Braintree, PayPal integrations, etc.).

Online processors typically require a method-specific object in the payload — e.g. Braintree needs a payment_method_nonce and is_active_payment_token_enabler. Check your gateway\'s schema additions.

mutation {
    setPaymentMethodOnCart(input: {
        cart_id: "rMQdWEecBZr4SVWZwj2AF6y0dNCKQ8uH"
        payment_method: { code: "banktransfer" }
    }) {
        cart {
            selected_payment_method { code title }
        }
    }
}

Required fields: cart_id (String!), payment_method.code (String!). Purchase Order payments also require purchase_order_number.

Finalizes the cart into an order and returns its number. From Commerce 2.4.7 onward the response exposes orderV2, which also carries a token usable with the guestOrderByToken query to fetch guest order details.

Prerequisites: a populated cart, billing + shipping addresses, a shipping method, a payment method, and — for guests — an email set via setGuestEmailOnCart.

Runs synchronously by default; when the AsyncOrder module is enabled it can run asynchronously, which helps at high volumes. Subsequent order lifecycle operations (invoice, ship, refund) must go through REST/SOAP — GraphQL only covers order placement.

mutation {
    placeOrder(
        input: { cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG" }
    ) {
        orderV2 { number token }
        errors { message code }
    }
}

Common error codes: CART_NOT_FOUND, CART_NOT_ACTIVE, GUEST_EMAIL_MISSING, UNABLE_TO_PLACE_ORDER (covers missing shipping/billing/payment, out-of-stock items, country-method mismatches).

Dica (PT-BR): gateways com redirect (PayPal, Stripe 3DS, Mercado Pago) costumam estender placeOrder com campos próprios. Consulte a documentação do gateway instalado.