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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.