Checkouts

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:

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 is created.

Checkout fields

Field	Type	Notes
`line_items`	array	Each item is `{ price_variant (required), quantity, amount }`. Add multiple to sell a bundle in one checkout. `amount` is only for pay-what-you-want items, see below.
`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, matched case-insensitively. It applies even when buyers can’t enter codes themselves. A code that doesn’t exist, is inactive, hasn’t started, has expired, has reached `max_redemptions`, doesn’t cover every line item, misses its `minimum_amount`, or that this `customer` or `email` can’t use under `once_per_customer` or `first_order_only` returns `400` and no checkout is created. A free checkout ignores it, and it can’t be combined with `invoice`. See Discounts.
`invoice`	string	An invoice id (`inv_...`) to pay — an alternative to `line_items`. See below.

Multiple line items

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 }
    ]
  }'

Pay-what-you-want items

For a price variant with amount_type: "custom", pass the buyer’s chosen unit price in amount (smallest currency unit, e.g. cents). The checkout total, each item’s amount in checkout_items, discount eligibility, and the resulting order all use it.

curl -X POST https://api.crevio.co/v1/checkouts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "buyer@example.com",
    "line_items": [{ "price_variant": "price_pwyw123", "quantity": 1, "amount": 2500 }]
  }'

Omit amount and the item uses the variant’s preset_amount, then its minimum_amount, then the smallest price Crevio charges in that currency.
An amount below minimum_amount, above maximum_amount, between zero and the currency’s smallest chargeable price, or that is not an integer returns 400 with code invalid_parameter. 0 is accepted only when minimum_amount is 0.
An amount on a fixed or free price variant returns 400.
The buyer can still change the amount on the hosted checkout page (purchase_url) within the same bounds before paying.

Paying an invoice

Instead of line items, pass an invoice id to create a checkout that settles that invoice:

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 for creating and managing invoices.

Worked example: sell to a customer end-to-end

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.purchaseUrl);

When the buyer pays, listen for the order.paid webhook event to fulfill the purchase. To run that whole path without charging a card, complete the checkout with POST /v1/checkouts/{id}/test_purchase, or open the purchase_url while signed in as the store’s owner and complete a test purchase. See Testing a paid order end to end.

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:

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.
`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.

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.
`allow_multiple_quantity`	bool	Let buyers change quantity at checkout.
`success_url`	string \| null	Default post-purchase redirect. Must be a full `https://` URL.
`abandoned_checkout_emails`	bool	Email buyers who gave an email but didn’t pay, with a link back to the same items. Off by default. See Abandoned checkout emails.
`abandoned_checkout_email_delay_hours`	integer	Hours after a checkout starts before its reminder is due, `1` to `72`. Defaults to `4`.

Changing this configuration expires every open checkout on the account (except changes to the two abandoned_checkout_* fields), 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

Discounts

Build the promo codes you apply via discount_code and discount.

Subscriptions & billing

Orders, invoices, refunds, and managing recurring revenue after checkout.

Products & pricing

Create the price variants your checkouts and links reference.

Webhooks

React to checkout.created, order.paid, and other events in real time.

Getting started

AI & agents

Core concepts

Integrations

Recipes

Creating a checkout

Checkout fields

Multiple line items

Pay-what-you-want items

Paying an invoice

Worked example: sell to a customer end-to-end

Reusable checkout links

Checkout link fields

Account-wide checkout settings

Next steps

Discounts

Subscriptions & billing

Products & pricing

Webhooks

​Creating a checkout

​Checkout fields

​Multiple line items

​Pay-what-you-want items

​Paying an invoice

​Worked example: sell to a customer end-to-end

​Reusable checkout links

​Checkout link fields

​Account-wide checkout settings

​Next steps

Discounts

Subscriptions & billing

Products & pricing

Webhooks

Creating a checkout

Checkout fields

Multiple line items

Pay-what-you-want items

Paying an invoice

Worked example: sell to a customer end-to-end

Reusable checkout links

Checkout link fields

Account-wide checkout settings

Next steps