Saleor Checkout

---
name: saleor-checkout
description: Implement the Saleor checkout flow — checkout creation, line items, shipping/billing addresses, delivery methods, payment, and completion. Use when building checkout experiences.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
---

# 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:

| Step | Mutation | Description |
|------|----------|-------------|
| 1. Create checkout | `checkoutCreate` | Initialize checkout with channel and lines |
| 2. Add/update lines | `checkoutLinesAdd` / `checkoutLinesUpdate` | Manage line items in the cart |
| 3. Set email | `checkoutEmailUpdate` | Set customer email (for guest checkout) |
| 4. Set shipping address | `checkoutShippingAddressUpdate` | Required for physical goods |
| 5. Set billing address | `checkoutBillingAddressUpdate` | Required for payment processing |
| 6. Select delivery method | `checkoutDeliveryMethodUpdate` | Choose shipping method or warehouse pickup |
| 7. Initialize payment | `transactionInitialize` | Start payment with payment App |
| 8. Process payment | `transactionProcess` | Handle additional payment steps (3DS, redirects) |
| 9. Complete checkout | `checkoutComplete` | Finalize and create the order |

> 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:

| Field | Required | Description |
|-------|----------|-------------|
| `channel` | Yes | Channel slug (determines currency, country, available products) |
| `lines` | Yes | Array of `{variantId, quantity}` objects |
| `email` | No | Customer email (can be set later) |
| `shippingAddress` | No | Shipping address (can be set later) |
| `billingAddress` | No | Billing address (can be set later) |

> **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:

| Aspect | Channel Impact |
|--------|---------------|
| Currency | Prices displayed in the channel currency |
| Country | Default country and allowed shipping destinations |
| Product availability | Only products with channel listings are purchasable |
| Shipping methods | Only shipping zones covering the channel's countries |
| Payment gateways | Only payment Apps configured for the channel |
| Tax calculation | Tax rules based on channel and country |

## Checkout Line Management

### Line Mutations

| Operation | Mutation | Notes |
|-----------|----------|-------|
| Add lines | `checkoutLinesAdd` | Add new variants to checkout |
| Update lines | `checkoutLinesUpdate` | Change quantities of existing lines |
| Delete lines | `checkoutLinesDelete` | Remove lines from checkout |
| Replace all lines | `checkoutLinesAdd` with `forceNewLine: false` | Merges with existing lines |

### Line Fields

| Field | Description |
|-------|-------------|
| `variant` | The product variant being purchased |
| `quantity` | Number of units |
| `totalPrice` | Calculated total for the line |
| `unitPrice` | Price per unit (includes discounts) |
| `undiscountedTotalPrice` | Price before promotions |
| `requiresShipping` | Whether this line needs physical delivery |

## Address Management

### Shipping Address

Setting the shipping address triggers recalculation of available delivery methods:

| Field | Required | Description |
|-------|----------|-------------|
| `firstName` | Yes | Customer first name |
| `lastName` | Yes | Customer last name |
| `streetAddress1` | Yes | Primary street address |
| `streetAddress2` | No | Additional address line |
| `city` | Yes | City name |
| `postalCode` | Varies | Postal or ZIP code |
| `country` | Yes | ISO 3166-1 alpha-2 country code |
| `countryArea` | Varies | State or province |
| `phone` | No | Phone number |

### 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:

| Method Type | Description |
|-------------|-------------|
| Shipping method | Standard carrier-based shipping (price or weight based) |
| Warehouse pickup | Click-and-collect from a physical warehouse |
| Custom shipping App | Dynamic rates from a shipping App via sync webhook |

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:

| Step | Mutation | Description |
|------|----------|-------------|
| 1. Initialize | `transactionInitialize` | Sends request to payment App; returns data or action needed |
| 2. Process (if needed) | `transactionProcess` | Handle additional steps like 3DS authentication |
| 3. Complete | `checkoutComplete` | Finalize checkout after successful payment |

### Transaction Initialize Input

| Field | Description |
|-------|-------------|
| `id` | Checkout ID |
| `paymentGateway` | Payment App ID and data (gateway-specific) |
| `amount` | Amount to charge (usually checkout total) |
| `idempotencyKey` | Unique key to prevent duplicate transactions |

### Transaction Initialize Response

| Field | Description |
|-------|-------------|
| `transaction` | Created transaction object |
| `transactionEvent` | Initial event (e.g., `CHARGE_REQUESTED`) |
| `data` | Gateway-specific response (e.g., client secret for Stripe) |

## Checkout Completion

After successful payment, call `checkoutComplete`:

| Outcome | Description |
|---------|-------------|
| Success | Returns `order` object; checkout is consumed |
| Confirmation needed | Returns `confirmationNeeded: true` with `confirmationData` |
| Error | Returns `errors` array with field and message |

> 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:

| Error Code | Cause | Resolution |
|------------|-------|------------|
| `INSUFFICIENT_STOCK` | Variant out of stock | Remove line or reduce quantity |
| `INVALID_SHIPPING_METHOD` | Selected method unavailable for address | Re-query available methods |
| `SHIPPING_ADDRESS_NOT_SET` | Missing shipping address | Set address before delivery method |
| `BILLING_ADDRESS_NOT_SET` | Missing billing address | Set address before payment |
| `VOUCHER_NOT_APPLICABLE` | Voucher invalid for this checkout | Remove voucher or adjust checkout |
| `CHECKOUT_NOT_FULLY_PAID` | Payment incomplete | Complete payment before checkout |

## Abandoned Checkout Handling

| Strategy | Description |
|----------|-------------|
| Query stale checkouts | Use `checkouts` query filtered by `lastChange` date |
| Email recovery | Send reminder emails for checkouts with email set |
| Metadata tracking | Use checkout `metadata` to store abandonment funnel data |
| TTL cleanup | Saleor automatically removes expired checkouts (configurable) |

> **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.