Skip to main content

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

Attributes

On a checkout that stores a card

A checkout created with setup_future_usage: "off_session" carries two more fields, on two different calls. Create Checkout Session returns setup_future_usage:
Get Checkout Status returns payment_method. It is null until the shopper has paid, then it holds the stored card:
The same payment_method is sent on the order.completed and payment_method.saved webhooks. See Saved Payment Methods.

Metadata that Gale reads

metadata holds your own key-value pairs. Gale acts on these keys:

Line Item Attributes

Checkout Session Status

These are the values on the object returned when you create a checkout. GET /api/v2/checkout/{checkout_id} reports progress with its own values: pending, completed, failed and expired. See Get Checkout Status.

Checkout Type

Gale automatically determines the type based on product eligibility:

Lifecycle

When status becomes paid:
  • An Order is created
  • order_id field is populated
  • order.completed webhook fires
  • Customer redirects to success_url

Tracking Checkout Status

The full response, with the order object and the stored card, is on Get Checkout Status. Response when open:
Response when paid:
Once paid, query the Order for full payment details:

Amounts Object

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:
When paid, creates both an Order and a Subscription object.
Subscription checkout is currently in Beta.

Webhooks

Checkout sessions trigger these webhooks:
  • order.completed — Payment succeeded, order created (this is what you should listen to)
  • order.failed — Payment failed
Note: Listen to order.completed to confirm payment.

Best Practices

Don’t poll for status — Use webhooks instead:
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.