---
title: "Create Checkout"
method: POST
path: "/api/v1/commerce/checkout"
tags: ["commerce", "commerce"]
---

# Create Checkout

`POST /api/v1/commerce/checkout`

## Request

- Base URL: `https://app.goodleads.club` (the document declares no server; this is the origin it was published from)
- URL: `https://app.goodleads.club/api/v1/commerce/checkout`
- Auth: API key in header `X-API-Key`

Start a Stripe Checkout Session — for a shelf product, or for a shaped list.

Returns the hosted Checkout URL — the frontend redirects the buyer.
A `commerce.order` row is created with status='pending' immediately;
the webhook flips it to 'paid' then 'delivered' as fulfillment completes.
A list order (ADR-045) also freezes its Run Manifest here, before payment.

Rate limited per IP to prevent orphan-session abuse.

## Request body

- CheckoutRequest: Buy a shelf product (`product_id`) OR a shaped list (ADR-045) — never both. A list is either a saved one (`list_id`) or an inline shape (`states` + `filters`); the buyer picks a lane, an optional cap (the dial) and how the records arrive. `price_rule_version` / `expected_total_cents` are the quote the buyer saw — when either has moved, the answer is a 409 carrying the fresh quote, never a silent different charge.
  - `product_id` string, nullable
  - `success_url` string, nullable
  - `cancel_url` string, nullable
  - `customer_email` string, nullable
  - `list_id` string, nullable
  - `states` string[], nullable
  - `filters` object[], nullable
  - `include_held` boolean
  - `include_existing` boolean
  - `lane` string, nullable
  - `cap` object, nullable
  - `channel` string, nullable
  - `contact` string, nullable
  - `delivery` string
  - `crm_connection_id` string, nullable
  - `connector_crm_name` string, nullable
  - `price_rule_version` integer, nullable
  - `expected_total_cents` integer, nullable
  - `offer_code` string, nullable

## Response `200`

Successful Response

- CheckoutResponse
  - `session_id` string, required
  - `checkout_url` string, required
  - `order_id` string, required
  - `quote` object, nullable
  - `saved_list` object, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/goodleads/apis/formation-gtm-api.md) · [All operations](https://skmtc.dev/goodleads/apis/formation-gtm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goodleads/apis/formation-gtm-api/revisions/2068d13a82cf?raw)