Saleor Checkout

Saleor Checkout Flow

Before writing code

Fetch live docs:

1. Web-search site:docs.saleor.io checkout flow steps for the end-to-end checkout process
2. Web-search site:docs.saleor.io checkout mutations graphql for checkout creation and update mutations
3. Web-search site:docs.saleor.io transaction payment checkout for the transaction-based payment flow
4. Fetch https://docs.saleor.io/docs/developer/checkout and review checkout lifecycle and required fields
5. Web-search site:docs.saleor.io delivery methods shipping checkout for shipping method selection
6. Fetch https://docs.saleor.io/docs/developer/payments and review payment initialization and completion

Checkout Flow Steps

The Saleor checkout follows a sequential flow:

Steps 3-6 can be done in any order, but all must be complete before payment initialization. The checkout validates required fields at each step.

Checkout Creation

Create a checkout by specifying the channel and initial line items:

Fetch live docs for the complete CheckoutCreateInput schema -- additional fields include languageCode, validationRules, and metadata.

Channel-Aware Checkout

Checkouts are always scoped to a channel:

Checkout Line Management

Line Mutations

Line Fields

Address Management

Shipping Address

Setting the shipping address triggers recalculation of available delivery methods:

Billing Address

Required before payment. Can be set independently or copied from shipping address. Uses the same address input schema.

Delivery Method Selection

After setting the shipping address, query available delivery methods:

Use checkoutDeliveryMethodUpdate to set the selected method by its ID.

Fetch live docs for the deliveryMethod union type -- it includes both ShippingMethod and Warehouse for pickup.

Payment Initialization (Transaction Flow)

Saleor uses a transaction-based payment model:

Transaction Initialize Input

Transaction Initialize Response

Checkout Completion

After successful payment, call checkoutComplete:

Checkout completion is idempotent -- calling it multiple times with the same checkout ID returns the same order.

Error Handling

Common checkout errors and their causes:

Abandoned Checkout Handling

Fetch live docs for checkout expiration settings and the checkouts admin query filter syntax.

Best Practices

• Always create checkouts scoped to a specific channel
• Validate stock availability before checkout completion (Saleor checks automatically, but early validation improves UX)
• Use transactionInitialize / transactionProcess for payments (not legacy checkoutPaymentCreate)
• Set both shipping and billing addresses before payment initialization
• Use idempotencyKey on transaction initialization to prevent duplicate charges
• Handle confirmationNeeded responses for payment methods requiring additional authentication
• Query availableShippingMethods and availablePaymentGateways dynamically after address changes
• Store custom data in checkout metadata for analytics and recovery workflows
• Implement error handling for every checkout step -- validate responses before proceeding

Fetch the Saleor checkout and transaction documentation for exact mutation inputs, error codes, and payment flow patterns before implementing.