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

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

AttributeTypeDescription
checkout_idstringUnique checkout session identifier
checkout_urlstringHosted checkout page URL to redirect customer
reference_idstringYour order/cart ID for correlation
statusenumSession status (see below)
typeenumCheckout type: eligible, split, or regular
customerobjectCustomer information
line_itemsarrayProducts being purchased
shipping_infoobjectShipping address
billing_infoobjectBilling address
amountsobjectPrice breakdown
success_urlstringRedirect URL after successful payment
failure_urlstringRedirect URL if payment fails or customer cancels
metadataobjectCustom key-value pairs
order_idstringCreated order ID (null until paid)
expires_attimestampWhen session expires (24 hours)
created_attimestampWhen session was created

​
Line Item Attributes

AttributeTypeDescription
product_idstringYour product ID
namestringProduct name
image_urlstringProduct image URL
priceintegerUnit price in cents
quantityintegerQuantity ordered
totalintegerLine total in cents (price x quantity)
currencystringCurrency code
hsa_fsa_eligiblebooleanWhether this item is HSA/FSA eligible

​
Checkout Session Status

StatusDescription
openSession created, awaiting customer
paidCustomer completed payment, order created
expiredSession expired (24 hours passed)

​
Checkout Type

Gale automatically determines the type based on product eligibility:
TypeDescription
eligibleAll items are HSA/FSA eligible
splitMix of eligible and non-eligible items
regularNo 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 /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 /v2/orders/{order_id}

​
Amounts Object

{
  "amounts": {
    "subtotal": 2995,
    "hsa_amount": 2995,
    "regular_amount": 0,
    "shipping": 995,
    "tax": 245,
    "discount": 0,
    "total": 4235
  }
}
FieldDescription
subtotalSum of all line item totals
hsa_amountAmount payable with HSA/FSA
regular_amountAmount requiring regular payment
shippingShipping cost
taxTax amount
discountDiscount applied
totalFinal 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.