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

# Checkout Session Object

> A temporary checkout session that leads to an Order when paid

# Checkout Session Object

A checkout session represents a temporary payment intent created when you redirect customers to Gale's hosted checkout page. When the customer completes payment, the session converts to an **Order**.

<Note>All monetary amounts are integers in cents (e.g., 4995 = \$49.95).</Note>

**Checkout sessions are ephemeral** — they expire after 24 hours. The **Order** object is your permanent payment record.

## The Checkout Session Object

```json theme={null}
{
  "checkout_id": "01HXYZ...",
  "checkout_url": "https://checkout.withgale.com/checkout/01HXYZ...",
  "reference_id": "your-order-123",
  "status": "open",
  "type": "eligible",
  "customer": {
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+1-555-123-4567"
  },
  "line_items": [
    {
      "product_id": "PROD-001",
      "name": "Digital Thermometer",
      "image_url": "https://yourcdn.com/thermometer.jpg",
      "price": 2995,
      "quantity": 1,
      "total": 2995,
      "currency": "USD",
      "hsa_fsa_eligible": true
    }
  ],
  "shipping_info": {
    "address_line_1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US"
  },
  "amounts": {
    "subtotal": 2995,
    "hsa_amount": 2995,
    "regular_amount": 0,
    "shipping": 995,
    "tax": 245,
    "discount": 0,
    "total": 4235
  },
  "success_url": "https://yoursite.com/order/success",
  "failure_url": "https://yoursite.com/order/failed",
  "metadata": {
    "platform": "custom"
  },
  "order_id": null,
  "expires_at": "2026-02-26T14:30:00Z",
  "created_at": "2026-02-25T14:30:00Z"
}
```

## Attributes

| Attribute       | Type      | Description                                       |
| --------------- | --------- | ------------------------------------------------- |
| `checkout_id`   | string    | Unique checkout session identifier                |
| `checkout_url`  | string    | Hosted checkout page URL to redirect customer     |
| `reference_id`  | string    | Your order/cart ID for correlation                |
| `status`        | enum      | Session status (see below)                        |
| `type`          | enum      | Checkout type: `eligible`, `split`, or `regular`  |
| `customer`      | object    | Customer information                              |
| `line_items`    | array     | Products being purchased                          |
| `shipping_info` | object    | Shipping address                                  |
| `billing_info`  | object    | Billing address                                   |
| `amounts`       | object    | Price breakdown                                   |
| `success_url`   | string    | Redirect URL after successful payment             |
| `failure_url`   | string    | Redirect URL if payment fails or customer cancels |
| `metadata`      | object    | Custom key-value pairs                            |
| `order_id`      | string    | Created order ID (null until paid)                |
| `expires_at`    | timestamp | When session expires (24 hours)                   |
| `created_at`    | timestamp | When session was created                          |

## Line Item Attributes

| Attribute          | Type    | Description                            |
| ------------------ | ------- | -------------------------------------- |
| `product_id`       | string  | Your product ID                        |
| `name`             | string  | Product name                           |
| `image_url`        | string  | Product image URL                      |
| `price`            | integer | Unit price in cents                    |
| `quantity`         | integer | Quantity ordered                       |
| `total`            | integer | Line total in cents (price x quantity) |
| `currency`         | string  | Currency code                          |
| `hsa_fsa_eligible` | boolean | Whether this item is HSA/FSA eligible  |

## Checkout Session Status

| Status    | Description                               |
| --------- | ----------------------------------------- |
| `open`    | Session created, awaiting customer        |
| `paid`    | Customer completed payment, order created |
| `expired` | Session expired (24 hours passed)         |

## Checkout Type

Gale automatically determines the type based on product eligibility:

| Type       | Description                            |
| ---------- | -------------------------------------- |
| `eligible` | All items are HSA/FSA eligible         |
| `split`    | Mix of eligible and non-eligible items |
| `regular`  | No items are eligible                  |

## Lifecycle

```
open → paid (payment succeeds, Order created)
  ↓
expired (24 hours, no payment)
```

When status becomes `paid`:

* An **Order** is created
* `order_id` field is populated
* `order.created` webhook fires
* Customer redirects to `success_url`

## Tracking Checkout Status

```bash theme={null}
GET /api/v2/checkout/{checkout_id}
```

**Response when open:**

```json theme={null}
{
  "checkout_id": "01HXYZ...",
  "status": "open",
  "order_id": null,
  "expires_at": "2026-02-26T14:30:00Z"
}
```

**Response when paid:**

```json theme={null}
{
  "checkout_id": "01HXYZ...",
  "status": "paid",
  "order_id": "ord_abc123",
  "paid_at": "2026-02-25T15:30:00Z"
}
```

Once paid, query the **Order** for full payment details:

```bash theme={null}
GET /api/v2/orders/{order_id}
```

## Amounts Object

```json theme={null}
{
  "amounts": {
    "subtotal": 2995,
    "hsa_amount": 2995,
    "regular_amount": 0,
    "shipping": 995,
    "tax": 245,
    "discount": 0,
    "total": 4235
  }
}
```

| Field            | Description                      |
| ---------------- | -------------------------------- |
| `subtotal`       | Sum of all line item totals      |
| `hsa_amount`     | Amount payable with HSA/FSA      |
| `regular_amount` | Amount requiring regular payment |
| `shipping`       | Shipping cost                    |
| `tax`            | Tax amount                       |
| `discount`       | Discount applied                 |
| `total`          | Final total charged              |

Gale automatically calculates how much can be paid with HSA/FSA vs regular payment methods based on product eligibility.

## Subscription Sessions

For subscription checkouts, include subscription details:

```json theme={null}
{
  "payment_type": "subscription",
  "subscription": {
    "interval": "monthly",
    "interval_count": 1,
    "trial_period_days": 14
  }
}
```

When paid, creates both an **Order** and a **Subscription** object.

<Note>Subscription checkout is currently in Beta.</Note>

## Webhooks

Checkout sessions trigger these webhooks:

* `order.created` — Payment succeeded, order created (this is what you should listen to)
* `order.failed` — Payment failed

**Note:** Listen to `order.created` to confirm payment.

## Best Practices

**Don't poll for status** — Use webhooks instead:

```javascript theme={null}
// Prefer: Webhooks
app.post('/webhooks/gale', (req, res) => {
  if (req.body.type === 'order.created') {
    await fulfillOrder(req.body.data);
  }
  res.status(200).send('OK');
});
```

**Sessions expire** — Don't store checkout URLs. Create new sessions for each purchase attempt.

**Order is your source of truth** — Once paid, always reference the Order object, not the checkout session.

## Related Endpoints

* [Create Checkout Session](/api-reference/endpoint/create-checkout-v2) — POST /api/v2/checkout
* [Get Checkout Session](/api-reference/endpoint/get-checkout) — GET /api/v2/checkout/{checkout_id}
* [List Orders](/api-reference/endpoint/list-orders) — GET /api/v2/orders

## Related Objects

* [Order Object](/api-reference/objects/order) — Permanent payment record
* [Product Object](/api-reference/objects/product) — Items being purchased
* [Subscription Object](/api-reference/objects/subscription) — For recurring payments