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.

All monetary amounts are integers in cents (e.g., 4995 = $49.95).

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

The Checkout Session Object

{
  "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

GET /api/v2/checkout/{checkout_id}

Response when open:

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

Response when paid:

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

GET /api/v2/orders/{order_id}

Amounts Object

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

{
  "payment_type": "subscription",
  "subscription": {
    "interval": "monthly",
    "interval_count": 1,
    "trial_period_days": 14
  }
}

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

Subscription checkout is currently in Beta.

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:

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

Create Checkout Session — POST /api/v2/checkout
Get Checkout Session — GET /api/v2/checkout/
List Orders — GET /api/v2/orders

Order Object — Permanent payment record
Product Object — Items being purchased
Subscription Object — For recurring payments

Getting Started

Integration Guides

Core Objects

Checkout

Payment Links

Orders

Products

Subscriptions

Webhooks & Errors

Checkout Session Object

Checkout Session Object

The Checkout Session Object

Attributes

Line Item Attributes

Checkout Session Status

Checkout Type

Lifecycle

Tracking Checkout Status

Amounts Object

Subscription Sessions

Webhooks

Best Practices

​Checkout Session Object

​The Checkout Session Object

​Attributes

​Line Item Attributes

​Checkout Session Status

​Checkout Type

​Lifecycle

​Tracking Checkout Status

​Amounts Object

​Subscription Sessions

​Webhooks

​Best Practices

​Related Endpoints

​Related Objects

Checkout Session Object

The Checkout Session Object

Attributes

Line Item Attributes

Checkout Session Status

Checkout Type

Lifecycle

Tracking Checkout Status

Amounts Object

Subscription Sessions

Webhooks

Best Practices

Related Endpoints

Related Objects