> ## Documentation Index
> Fetch the complete documentation index at: https://docs.colossal.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout

> Create and manage checkout sessions via the Storefront API.

## Queries

### `checkoutSession`

Fetch a checkout session with payment and order details.

```graphql theme={null}
query CheckoutSession($uid: UUID!) {
  checkoutSession(uid: $uid) {
    uid
    status
    checkoutUrl
    readyForPayment
    requiredFields
    checkoutValidationIssues
    selectedPaymentProvider
    shippingOptions {
      uid
      displayName
      amount
    }
    paymentSession {
      uid
      provider
      status
      amount
      currency
      providerRef
      clientToken
      paymentMethods
    }
    order {
      uid
      status
      totalAmount
    }
    invoice {
      uid
      total
      status
    }
    expiresAt
    completedAt
  }
}
```

## Mutations

### `createCheckoutSession`

Create a checkout session from a cart.

```graphql theme={null}
mutation CreateCheckoutSession(
  $cartUid: UUID!
  $guestEmail: String
  $guestName: String
) {
  createCheckoutSession(
    cartUid: $cartUid
    guestEmail: $guestEmail
    guestName: $guestName
  ) {
    success
    data {
      uid
      checkoutUrl
      status
    }
  }
}
```

**Arguments:**

| Field        | Type     | Required | Description              |
| ------------ | -------- | -------- | ------------------------ |
| `cartUid`    | `UUID`   | Yes      | Cart to check out        |
| `guestEmail` | `String` | No       | Email for guest checkout |
| `guestName`  | `String` | No       | Name for guest checkout  |

### `updateCheckoutSession`

Update checkout details (address, payment provider, shipping).

```graphql theme={null}
mutation UpdateCheckoutSession(
  $sessionUid: UUID!
  $input: CheckoutSessionUpdateInput!
) {
  updateCheckoutSession(sessionUid: $sessionUid, input: $input) {
    success
    data {
      uid
      readyForPayment
      checkoutValidationIssues
    }
  }
}
```

**Input:**

| Field                     | Type                 | Description                 |
| ------------------------- | -------------------- | --------------------------- |
| `selectedPaymentProvider` | `String?`            | Payment provider ID         |
| `customer`                | `CustomerInfoInput?` | Customer email, name, phone |
| `billingAddress`          | `AddressInput?`      | Billing address             |
| `shippingAddress`         | `AddressInput?`      | Shipping address            |
| `selectedShippingOption`  | `String?`            | Shipping option UID         |

### `completeCheckoutSession`

Complete payment and finalize the order.

```graphql theme={null}
mutation CompleteCheckoutSession(
  $sessionUid: UUID!
  $paymentMethodType: String
  $paymentMethodId: String
  $pspPayload: JSON
  $returnUrl: String
) {
  completeCheckoutSession(
    sessionUid: $sessionUid
    paymentMethodType: $paymentMethodType
    paymentMethodId: $paymentMethodId
    pspPayload: $pspPayload
    returnUrl: $returnUrl
  ) {
    success
    data {
      uid
      status
      order { uid status }
    }
  }
}
```

## Types

### CheckoutSession

| Field                      | Type                                        | Description                             |
| -------------------------- | ------------------------------------------- | --------------------------------------- |
| `uid`                      | `UUID`                                      | Session ID                              |
| `status`                   | `OPEN \| COMPLETED \| EXPIRED \| ABANDONED` | Session status                          |
| `checkoutUrl`              | `String`                                    | Hosted checkout URL                     |
| `readyForPayment`          | `Boolean`                                   | Whether all required fields are set     |
| `requiredFields`           | `[String]`                                  | `BILLING_ADDRESS`, `SHIPPING_ADDRESS`   |
| `checkoutValidationIssues` | `[String]`                                  | Validation errors preventing completion |
| `selectedPaymentProvider`  | `String?`                                   | Selected provider ID                    |
| `shippingOptions`          | `[ShippingOption]`                          | Available shipping options              |
| `paymentSession`           | `PaymentSession?`                           | Payment provider session                |
| `order`                    | `Order?`                                    | Associated order                        |
| `invoice`                  | `Invoice?`                                  | Associated invoice                      |
| `expiresAt`                | `DateTime`                                  | Session expiry                          |
| `completedAt`              | `DateTime?`                                 | Completion timestamp                    |

### PaymentSession

| Field            | Type                         | Description                                                                 |
| ---------------- | ---------------------------- | --------------------------------------------------------------------------- |
| `uid`            | `UUID`                       | Session ID                                                                  |
| `provider`       | `String`                     | Provider ID (e.g. `stripe-payment-gateway`)                                 |
| `status`         | `READY \| PENDING \| FAILED` | Payment status                                                              |
| `amount`         | `Int`                        | Amount in minor currency units (cents)                                      |
| `currency`       | `String`                     | ISO currency code                                                           |
| `providerRef`    | `String?`                    | Provider reference (e.g. Stripe PaymentIntent ID)                           |
| `clientToken`    | `String?`                    | Client-side token for embedded payment flows                                |
| `paymentMethods` | `[String]`                   | `CARD`, `APPLE_PAY`, `GOOGLE_PAY`, `PAYPAL`, `KLARNA`, `AMAZON_PAY`, `LINK` |

### ShippingOption

| Field         | Type     | Description                          |
| ------------- | -------- | ------------------------------------ |
| `uid`         | `String` | Option ID                            |
| `displayName` | `String` | Display name                         |
| `amount`      | `Int`    | Cost in minor currency units (cents) |

### AddressInput

| Field        | Type      |
| ------------ | --------- |
| `line1`      | `String?` |
| `line2`      | `String?` |
| `city`       | `String?` |
| `state`      | `String?` |
| `postalCode` | `String?` |
| `country`    | `String?` |