> ## Documentation Index
> Fetch the complete documentation index at: https://crevio.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Checkouts
> Take payment with one-off checkouts and reusable checkout links — line items, customers, discount codes, and paying invoices.
**A checkout is a single pay-for-this session; a checkout link is a reusable, shareable URL that opens one.** Both turn your published price variants into money.
You can ask Crevio to "send Jane a checkout for the \$99 course with the LAUNCH20 code" and the agent builds it through the same API below. For programmatic flows — custom websites, "buy now" buttons, invoicing — you'll create checkouts directly.
## Creating a checkout
`POST /checkouts` takes one or more line items, each pointing at a price variant by id:
```bash theme={null}
curl -X POST https://api.crevio.co/v1/checkouts \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "jane@example.com",
"line_items": [
{ "price_variant": "price_abc123", "quantity": 1 }
]
}'
```
The response is a checkout (`"object": "checkout"`, id like `co_...`) with a URL the buyer visits to pay. When they complete it, an [order](/docs/developer/guides/subscriptions-and-billing#orders-the-read-model) is created.
### Checkout fields
| Field | Type | Notes |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| `line_items` | array | Each item is `{ price_variant (required), quantity }`. Add multiple to sell a bundle in one checkout. |
| `email` | string | The buyer's email. Use this for a brand-new buyer. |
| `customer` | string | An existing customer id (`cus_...`). Use instead of `email` to attach the purchase to a known customer. |
| `discount_code` | string | A discount code applied to this checkout. See [Discounts](/docs/developer/guides/discounts). |
| `invoice` | string | An invoice id (`inv_...`) to pay — an alternative to `line_items`. See below. |
### Multiple line items
```bash theme={null}
curl -X POST https://api.crevio.co/v1/checkouts \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customer": "cus_xyz789",
"discount_code": "LAUNCH20",
"line_items": [
{ "price_variant": "price_abc123", "quantity": 1 },
{ "price_variant": "price_def456", "quantity": 2 }
]
}'
```
### Paying an invoice
Instead of line items, pass an `invoice` id to create a checkout that settles that invoice:
```bash theme={null}
curl -X POST https://api.crevio.co/v1/checkouts \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "invoice": "inv_abc123" }'
```
See [Subscriptions & billing](/docs/developer/guides/subscriptions-and-billing#invoices) for creating and managing invoices.
## Worked example: sell to a customer end-to-end
```typescript theme={null}
import { Crevio } from "@crevio/sdk";
const crevio = new Crevio({ apiKeyAuth: "YOUR_API_TOKEN" });
// 1. Create (or look up) the customer.
const customer = await crevio.customers.create({
email: "jane@example.com",
name: "Jane Doe",
customer_type: "lead",
});
// 2. Create a checkout for them, applying a launch discount.
const checkout = await crevio.checkouts.create({
customer: customer.id,
discount_code: "LAUNCH20",
line_items: [{ price_variant: "price_abc123", quantity: 1 }],
});
// 3. Send the buyer to the checkout URL to pay.
console.log(checkout.url);
```
When the buyer pays, listen for the `order.paid` [webhook event](/docs/developer/guides/webhooks) to fulfill the purchase.
## Reusable checkout links
When you want one durable URL to share — in a bio link, an email, a "buy now" button — create a **checkout link** with `POST /checkout_links`:
```bash theme={null}
curl -X POST https://api.crevio.co/v1/checkout_links \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Guitar course launch",
"price_variants": ["price_abc123"],
"discount": "disc_launch20",
"allow_discount_codes": true,
"success_url": "https://example.com/thanks",
"metadata": { "campaign": "summer-launch" }
}'
```
### Checkout link fields
| Field | Type | Notes |
| ---------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| `name` | string | Internal label for the link. |
| `price_variants` | array | The price variant ids (`price_...`) the link sells. |
| `discount` | string | A discount id (`disc_...`) applied automatically. See [Discounts](/docs/developer/guides/discounts). |
| `allow_discount_codes` | bool | Whether buyers can enter their own code at checkout. |
| `success_url` | string | Where to send the buyer after a successful purchase. |
| `metadata` | object | Arbitrary key/values that flow through to the resulting order — handy for attribution. |
The response includes an id (`cl_...`) and the shareable URL. Checkout links support full CRUD — update, list, retrieve, and delete them like any other resource.
Use a **checkout** for a one-off, often personalized sale (you know the buyer), and a **checkout link** for an evergreen, shareable offer (anyone can open it).
## Account-wide checkout settings
The defaults every checkout inherits — tax, address collection, which inputs the buyer sees — live on a single account-wide resource at `/v1/checkout_configuration`. It is a singleton: no id, `GET` to read and `PATCH` to change.
```bash theme={null}
curl -X PATCH https://api.crevio.co/v1/checkout_configuration \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"collect_tax": true,
"tax_behavior": "exclusive",
"allowed_countries": ["US", "CA", "GB"],
"show_tax_id_input": true
}'
```
| Field | Type | Notes |
| -------------------------- | -------------- | -------------------------------------------------------------------------------------------------- |
| `allowed_countries` | array | ISO country codes the buyer's address may be in. Empty means no restriction. |
| `collect_tax` | bool | Whether tax is calculated at checkout. |
| `tax_behavior` | string | `unspecified`, `inclusive`, or `exclusive` — whether your prices already include tax. |
| `tax_code` | string | The product tax code applied by default (`txcd_…`). |
| `allow_discount_codes` | bool | Whether buyers can enter a code, unless a checkout overrides it. |
| `show_tax_id_input` | bool | Show a business tax ID field (needed for B2B VAT reverse charge). |
| `show_phone_number_input` | bool | Collect a phone number. |
| `collect_call_consent` | bool | Ask for explicit consent to be called. |
| `collect_shipping_address` | bool | Collect a shipping address. Required for [physical goods](/docs/developer/guides/products-and-pricing). |
| `allow_multiple_quantity` | bool | Let buyers change quantity at checkout. |
| `success_url` | string \| null | Default post-purchase redirect. Must be a full `https://` URL. |
Changing this configuration **expires every open checkout on the account**, so buyers mid-purchase get a fresh session on the new settings rather than one priced under the old ones. Expect to re-create any checkout id you were holding on to. When `collect_tax` or `tax_behavior` changes, your Stripe tax settings are updated to match.
## Next steps
Build the promo codes you apply via `discount_code` and `discount`.
Orders, invoices, refunds, and managing recurring revenue after checkout.
Create the price variants your checkouts and links reference.
React to `checkout.created`, `order.paid`, and other events in real time.