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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
      "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

Getting Started

Integration Guides

Core Objects

Checkout

Payment Links

Orders

Products

Subscriptions

Webhooks & Errors

Create Checkout Session

Create Checkout Session

Base URL

Authentication

Request Body

Parameters

Response

Examples

Basic Checkout

With JavaScript

Subscription Checkout

Checkout Status

Webhooks

Errors

Getting Started

Integration Guides

Core Objects

Checkout

Payment Links

Orders

Products

Subscriptions

Webhooks & Errors

​Create Checkout Session

​Base URL

​Authentication

​Request Body

​Parameters

​Response

​Examples

​Basic Checkout

​With JavaScript

​Subscription Checkout

​Checkout Status

​Webhooks

​Errors

​Related Resources

Create Checkout Session

Base URL

Authentication

Request Body

Parameters

Response

Examples

Basic Checkout

With JavaScript

Subscription Checkout

Checkout Status

Webhooks

Errors

Related Resources