Skip to main content

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.

Payment happens on Gale’s secure hosted page. These endpoints control the checkout lifecycle.

​
Create Checkout

POST /v1/checkout
Content-Type: application/json
Authorization: Bearer <merchant_api_token>
Idempotency-Key: <uuid-v4>

​
One-Time Payment

{
  "customer": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com"
  },
  "line_items": [
    {
      "product_id": "prod_abc123",
      "price_cents": 5000,
      "quantity": 1
    }
  ],
  "shipping_amount_cents": 700,
  "tax_amount_cents": 350,
  "discount_amount_cents": 0,
  "total_amount_cents": 6050,
  "currency": "usd",
  "external_cart_id": "cart-789"
}

​
Subscription Payment

For recurring billing, include subscription plans created via the Plans API: 
{
  "customer": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com"
  },
  "line_items": [
    {
      "product_id": "prod_abc123",
      "plan_id": "plan_monthly_contacts",
      "price_cents": 2500,
      "quantity": 1
    }
  ],
  "shipping_amount_cents": 0,
  "tax_amount_cents": 200,
  "total_amount_cents": 2700,
  "currency": "usd",
  "external_cart_id": "cart-789",
  "subscription_config": {
    "billing_cycle_anchor": "2025-07-01",
    "trial_days": 7
  }
}

​
Mixed Cart (One-time + Subscription)

{
  "customer": {
    "first_name": "Jane",
    "last_name": "Doe", 
    "email": "jane@example.com"
  },
  "line_items": [
    {
      "product_id": "prod_starter_kit",
      "price_cents": 4900,
      "quantity": 1
    },
    {
      "product_id": "prod_monthly_supply",
      "plan_id": "plan_monthly_supply",
      "price_cents": 2500,
      "quantity": 1
    }
  ],
  "total_amount_cents": 7400,
  "currency": "usd"
}

​
Payment Method Storage

To save payment methods for future charges without predefined subscription plans add following keys to checkout request: 
{
  "setup_future_usage": "on_session",
  "metadata": {
    "subscription_intent": "custom_billing_cycle"
  }
}

​
Subscription Parameters

  • plan_id — Subscription plan created via Plans API (required for recurring items)
  • subscription_config.billing_cycle_anchor — When to start billing cycles (ISO date)
  • subscription_config.trial_days — Free trial period before first charge
  • setup_future_usage — on_session for saving payment methods without predefined plans
Success 201 
{
  "checkout_id": "chk_123",
  "status": "UNPAID", 
  "checkout_url": "https://checkout.withgale.com/chk_123",
  "expires_at": "2025-06-05T12:30:00Z"
}

​
Hosted Page Behavior

For Subscriptions:
  • Customer sees subscription terms and billing frequency
  • HSA/FSA card eligibility verified for subscription products
  • Payment method automatically saved for future billing
For One-time + Setup:
  • Standard checkout flow
  • Optional consent to save payment method for future use
Redirect your shopper to checkout_url.

​
Get Checkout Status

GET /v1/checkout/{checkout_id}
Authorization: Bearer <merchant_api_token>
Response 
{
  "checkout_id": "chk_123",
  "status": "PAID",
  "purchase_type": "subscription", 
  "payment_method_id": "pm_456abc",
  "subscription_items": [
    {
      "plan_id": "plan_monthly_contacts",
      "plan_name": "Monthly Contact Lens Supply",
      "interval": "monthly",
      "price_cents": 2500,
      "quantity": 1,
      "next_billing_date": "2025-07-01"
    }
  ],
  "one_time_items": [
    {
      "product_id": "prod_starter_kit",
      "price_cents": 4900,
      "quantity": 1
    }
  ],
  "amount_paid_cents": 7400,
  "currency": "usd",
  "paid_at": "2025-06-05T12:04:12Z",
  "subscription_agreement": {
    "agreed_at": "2025-06-05T12:03:45Z",
    "terms_version": "v2.1",
    "billing_consent": true
  }
}

​
Purchase Types

  • one_time — No subscriptions, payment method optionally saved
  • subscription — All items are recurring plans
  • mixed — Combination of one-time products and subscription plans

​
Subscription Agreement

When subscriptions are involved, the response includes:
  • subscription_agreement.agreed_at — When customer agreed to recurring billing
  • subscription_agreement.terms_version — Version of terms they accepted
  • subscription_agreement.billing_consent — Explicit consent to future charges

​
Payment Method Storage

  • payment_method_id — Available when payment succeeds and recurring billing is enabled
  • Use with Subscription Charge API for future billing
Status values: UNPAID, PAID, REFUNDED, CANCELLED, EXPIRED.

​
Refund Checkout

Partial or full refund. Omit line_items for a full refund. 
POST /v1/checkout/{checkout_id}/refund
Content-Type: application/json
Authorization: Bearer <merchant_api_token>
Idempotency-Key: <uuid-v4>
Partial Refund Body 
{
  "line_items": [
    { "line_item_id": "li_01", "quantity": 1, "amount_cents": 100 }
  ],
  "reason": "Damaged item"
}
Success 200 
{
  "checkout_id": "chk_123",
  "status": "REFUNDED",
  "refunded_amount_cents": 5000,
  "currency": "usd", 
  "refunded_at": "2025-06-05T12:10:22Z"
}

​
Cancel Checkout

Allowed only while status is UNPAID. 
POST /v1/checkout/{checkout_id}/cancel
Authorization: Bearer <merchant_api_token>
Idempotency-Key: <uuid-v4>
Success 200 
{
  "checkout_id": "chk_123",
  "status": "CANCELLED",
  "cancelled_at": "2025-06-05T12:08:00Z"
}
Cancelling a paid/expired session returns 409 Conflict.
Subscribe to the checkoutStatusChange webhook for live status updates. For subscriptions, the webhook includes payment_method_id and subscription agreement details for successful payments.