Create Checkout Session

Create a checkout session and get a hosted checkout URL

Create Checkout Session

Create a checkout session for a customer. Returns a checkout URL where the customer completes payment on Gale’s hosted page. Gale handles card collection, eligibility detection, and LMN flow automatically.

Base URL

https://carts.withgale.com

Authentication

Authorization: Bearer glm_test_YOUR_API_KEY

Request Body

{
  "plugin_version": "1.0.1",
  "test_mode": false,
  "merchant_cart_id": "e17580b9-0637-405c-b507-28230f2db7ba",
  "customer": {
    "email": "[e-mail]",
    "first_name": "Hulda",
    "last_name": "Klocko",
    "phone": "271-970-2219",
    "timezone": "America/Chicago"
  },
  "metadata": {
    "platform": "SHOPIFY",
    "webhook_url": "https://your-server.com/payment-webhook"
  },
  "shipping_info": {
    "address_line_1": "901 L Street Northwest",
    "address_line_2": null,
    "state": "Washington DC",
    "city": "Washington",
    "zip": "20001",
    "country": "US"
  },
  "billing_info": {
    "address_line_1": "901 L Street Northwest",
    "address_line_2": null,
    "state": "Washington DC",
    "city": "Washington",
    "zip": "20001",
    "country": "US"
  },
  "shipping_amount": 0,
  "discount": 0,
  "tax_amount": 0,
  "success_url": "https://your-site.com/payment/success",
  "failure_url": "https://your-site.com/payment/failed",
  "line_items": [
    {
      "merchant_product_id": null,
      "name": "Shopify Product",
      "product_picture": "https://via.placeholder.com/150",
      "product_amount": 101,
      "quantity": 1,
      "currency_code": "USD"
    },
    {
      "merchant_product_id": 232,
      "name": "Shopify Product",
      "product_picture": "https://via.placeholder.com/150",
      "product_amount": 201,
      "quantity": 1,
      "currency_code": "USD"
    }
  ]
}

Parameters

Parameter	Type	Required	Description
plugin_version	string	Yes	Plugin or integration version
test_mode	boolean	Yes	Process transaction in test mode
merchant_cart_id	string	Yes	Unique cart ID from your platform
customer	object	Yes	Customer information
customer.email	string	Yes	Customer email
customer.first_name	string	Yes	Customer first name
customer.last_name	string	Yes	Customer last name
customer.phone	string	No	Customer phone number
customer.timezone	string	No	Customer timezone (e.g., "America/Chicago")
line_items	array	Yes	Products being purchased
line_items[].merchant_product_id	string or number	No	Your product ID (nullable for some platforms)
line_items[].name	string	Yes	Product name
line_items[].product_picture	string	No	Image URL of the product
line_items[].product_amount	integer	Yes	Unit price of the product in cents
line_items[].quantity	integer	Yes	Quantity
line_items[].currency_code	string	Yes	Currency (e.g., "USD")
shipping_info	object	Yes	Shipping address
shipping_info.address_line_1	string	Yes	Address line 1
shipping_info.address_line_2	string	No	Address line 2
shipping_info.state	string	Yes	State
shipping_info.city	string	Yes	City
shipping_info.zip	string	Yes	ZIP/Postal code
shipping_info.country	string	Yes	Country code (e.g., "US")
billing_info	object	Yes	Billing Address
billing_info.address_line_1	string	Yes	Address line 1
billing_info.address_line_2	string	Yes	Address line 2
billing_info.state	string	Yes	State
billing_info.city	string	Yes	City
billing_info.zip	string	Yes	Zip/postal code
billing_info.country	string	Yes	Country code (e.g., "US")
shipping_amount	integer	No	Shipping fee amount in cents
discount	integer	No	Discount amount in cents
tax_amount	integer	No	Tax amount in cents
success_url	string	Yes	Redirect URL after successful payment
failure_url	string	Yes	Redirect URL if payment fails
metadata	object	No	Custom key-value pairs
metadata.platform	string	No	Platform name (e.g., SHOPIFY)
metadata.webhook_url	string	No	URL to receive payment status webhook (recommended)

Response

{
  "success": true,
  "payment": {
    "redirect_url": "https://checkout.staging.withgale.com/checkout/01K94XXXXXXXXXXXXXXXX",
    "cart_id": "01K94XXXXXXXXXXXXXXXX",
    "redirect_mode": "modal"
  }
}

Examples

Basic Checkout

curl --location 'https://carts.withgale.com/api/v1/cart' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
  "plugin_version": "1.0.1",
  "test_mode": false,
  "merchant_cart_id": "e17580b9-0637-405c-b507-28230f2db7ba",
  "customer": {
    "email": "[e-mail]",
    "first_name": "Hulda",
    "last_name": "Klocko",
    "phone": "271-970-2219",
    "timezone": "America/Chicago"
  },
  "metadata": {
    "platform": "CUSTOM",
    "webhook_url": "https://your-server.com/payment-webhook"
  },
  "shipping_info": {
    "address_line_1": "901 L Street Northwest",
    "state": "Washington DC",
    "city": "Washington",
    "zip": "20001",
    "country": "US"
  },
  "billing_info": {
    "address_line_1": "901 L Street Northwest",
    "state": "Washington DC",
    "city": "Washington",
    "zip": "20001",
    "country": "US"
  },
  "shipping_amount": 0,
  "discount": 0,
  "tax_amount": 0,
  "success_url": "https://your-site.com/payment/success",
  "failure_url": "https://your-site.com/payment/failed",
  "line_items": [
    {
      "merchant_product_id": null,
      "name": "Shopify Product",
      "product_picture": "https://via.placeholder.com/150",
      "product_amount": 101,
      "quantity": 1,
      "currency_code": "USD"
    },
    {
      "merchant_product_id": 232,
      "name": "Shopify Product",
      "product_picture": "https://via.placeholder.com/150",
      "product_amount": 201,
      "quantity": 1,
      "currency_code": "USD"
    }
  ]
}'

With JavaScript

const createCheckoutSession = async (cart) => {
  try {
    const response = await fetch('https://carts.withgale.com/api/v1/cart', {
      method: 'POST',
      headers: {
        "Authorization": `Bearer ${process.env.GALE_API_KEY}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        plugin_version: "1.0.1",
        test_mode: false,
        merchant_cart_id: cart.id,
        customer: {
          email: cart.email,
          first_name: cart.firstName,
          last_name: cart.lastName,
          phone: cart.phone,
          timezone: cart.timezone
        },
        metadata: {
          platform: "CUSTOM",
          webhook_url: "https://your-server.com/payment-webhook"
        },
        shipping_info: cart.shippingAddress,
        billing_info: cart.billingAddress,
        shipping_amount: cart.shippingAmount,
        discount: cart.discount || 0,
        tax_amount: cart.taxAmount || 0,
        success_url: "https://your-site.com/payment/success",
        failure_url: "https://your-site.com/payment/failed",
        line_items: cart.items.map(item => ({
          merchant_product_id: item.id ?? null,
          name: item.name,
          product_picture: item.image,
          product_amount: item.price,
          quantity: item.quantity,
          currency_code: item.currency || "USD"
        }))
      })
    });

    const data = await response.json();

    if (!data.success) {
      console.error("Failed to create checkout session:", data);
      return;
    }

    // Redirect customer to Gale Hosted Checkout
    window.location.href = data.payment.redirect_url;

  } catch (error) {
    console.error("Error creating checkout session:", error);
  }
};

Subscription Checkout

curl -X POST https://api.withgale.com/v2/checkout \
  -H "Authorization: Bearer glm_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "email": "[e-mail]",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "line_items": [
      {
        "merchant_product_id": "MEMBERSHIP-PREMIUM",
        "name": "Premium Membership",
        "quantity": 1,
        "price_cents": 9900
      }
    ],
    "payment_type": "subscription",
    "subscription": {
      "interval": "monthly",
      "trial_period_days": 14
    },
    "success_url": "https://yoursite.com/welcome",
    "cancel_url": "https://yoursite.com/pricing"
  }'

Checkout Status

Status	Description
open	Checkout session created, awaiting customer
complete	Customer completed payment
expired	Session expired (24 hours)

Webhooks

When payment is complete, receive webhook:

{
  "type": "order.created",
  "data": {
    "id": "ord_xyz789",
    "checkout_session_id": "checkout_abc123xyz",
    "status": "completed",
    "customer": {...},
    "line_items": [...]
  }
}

See Webhooks Reference.

Errors

Status Code	Error Code	Description
400	invalid_request	Missing or invalid parameters
401	unauthorized	Invalid API key
422	validation_error	Field validation failed

Related Resources

• Checkout Integration Guide
• Order Object
• Webhooks