Subscriptions & billing

Once buyers start paying, Crevio gives you the read-and-act surface for the money side: subscriptions, invoices, refunds, and the order record behind every purchase. Subscriptions and orders are largely read models you act on; invoices and refunds you create. You can ask Crevio to “pause Jane’s subscription until next month” or “refund order ord_abc123” and the agent calls the same endpoints below. For automated billing flows, you’ll call them directly.

Subscriptions

A subscription (sub_...) is created when a buyer pays for a subscription price variant. You don’t create subscriptions over the API — you list, retrieve, and change their state.

List and retrieve

# List subscriptions
curl https://api.crevio.co/v1/subscriptions \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Retrieve one
curl https://api.crevio.co/v1/subscriptions/sub_abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Change subscription state

Each lifecycle action is its own POST sub-route:

Action	Endpoint
Cancel	`POST /subscriptions/{id}/cancel`
Pause	`POST /subscriptions/{id}/pause`
Resume	`POST /subscriptions/{id}/resume`

# Pause a subscription
curl -X POST https://api.crevio.co/v1/subscriptions/sub_abc123/pause \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Resume it later
curl -X POST https://api.crevio.co/v1/subscriptions/sub_abc123/resume \
  -H "Authorization: Bearer YOUR_API_TOKEN"

await crevio.subscriptions.cancel({ id: "sub_abc123" });

Subscription lifecycle is observable via webhooks: subscription.created, subscription.renewed, subscription.canceled, subscription.paused, subscription.resumed, subscription.past_due, and subscription.ended. See Webhooks.

Cancellation feedback

When a customer cancels from the hosted billing page, the subscription carries what they told you in cancellation_details — on GET /subscriptions/{id} and in the subscription.* webhook payloads, including subscription.canceled:

"cancellation_details": {
  "reason": "too_expensive",
  "comment": "Money is tight this month.",
  "requested_at": "2026-10-20T09:14:02Z"
}

reason is one of too_expensive, missing_features, switched_service, unused, customer_service, too_complex, low_quality, other, or null when the reason question was turned off. cancellation_details is null for a subscription that was never cancelled from the billing page, and it keeps the most recent cancellation if the customer cancelled, resumed, and cancelled again. What the billing page shows before a cancellation goes through is set on the checkout configuration (PATCH /checkout_configuration):

Field	Meaning
`cancellation_message`	Text shown first. `null` skips the step.
`cancellation_pause_max_intervals`	Offer a pause of 1 to this many billing periods (1-12). `null` turns it off.
`cancellation_discount`	A discount ID (`disc_...`) offered once per customer. `null` turns it off.
`cancellation_reasons`	The reasons offered, from the list above. `[]` skips the question. Defaults to all eight.

curl -X PATCH https://api.crevio.co/v1/checkout_configuration \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cancellation_pause_max_intervals": 3, "cancellation_discount": "disc_abc123"}'

A subscription paused from the billing page reads "paused": true and restarts billing on its own when the pause ends.

Discount an existing subscription

A subscription carries at most one discount, exposed as discount on the subscription object (an ID by default, the full object with ?expand=discount). Set it with PUT, clear it with DELETE:

# Apply a discount (replaces any discount already on the subscription)
curl -X PUT https://api.crevio.co/v1/subscriptions/sub_abc123/discount \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"discount": "disc_abc123"}'

# Remove it
curl -X DELETE https://api.crevio.co/v1/subscriptions/sub_abc123/discount \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Nothing is charged or refunded when you call either endpoint. The change takes effect from the next invoice, and how long it lasts follows the discount’s duration (once, repeating, or forever). The subscription itself is untouched — same customer, price, billing date, and access — so use this instead of cancelling and re-creating a subscription to change what a customer pays. PUT is idempotent: applying the discount a subscription already has returns it unchanged. The request is rejected with 400 when the subscription has ended, is a payment plan (its total is fixed), or when the discount is inactive, expired, or restricted to price variants the subscription isn’t for.

Invoices

An invoice (inv_...) is a request for payment you send to a customer. Create one, then the customer pays it by opening a checkout.

Create an invoice

curl -X POST https://api.crevio.co/v1/invoices \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_xyz789",
    "customer_name": "Jane Doe",
    "email_address": "jane@example.com",
    "price_variant": "price_abc123",
    "description": "Consulting session — June",
    "due_at": "2026-07-01T00:00:00Z"
  }'

Field	Notes
`customer`	The customer id (`cus_...`) being billed.
`customer_name` / `email_address`	Recipient details for the invoice.
`price_variant`	The price variant (`price_...`) this invoice charges for.
`description`	Free-text line shown on the invoice.
`due_at`	When payment is due (date-time).

Pay an invoice

Paying an invoice goes through a checkout — pass the invoice id as the invoice param:

curl -X POST https://api.crevio.co/v1/checkouts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invoice": "inv_abc123" }'

The returned checkout URL is what the customer uses to pay. See Checkouts.

Void an invoice

To cancel an unpaid invoice:

curl -X POST https://api.crevio.co/v1/invoices/inv_abc123/void \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Invoice lifecycle is observable via webhooks: invoice.created, invoice.paid, invoice.past_due, and invoice.voided.

Refunds

A refund returns money on an existing order. The only required field is the order; omit amount for a full refund, or pass an amount in cents for a partial one.

Full refund

curl -X POST https://api.crevio.co/v1/refunds \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "order": "ord_abc123" }'

Partial refund

curl -X POST https://api.crevio.co/v1/refunds \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order": "ord_abc123",
    "amount": 2000,
    "reason": "requested_by_customer",
    "notes": "Refunding one of two seats."
  }'

amount: 2000 refunds $20.00 of the order. The optional reason and notes are recorded with the refund. Refunds are also listable and retrievable, and emit refund.created / refund.updated webhooks. An order whose status is disputed can’t be refunded: the request returns 422 with Order is not refundable, because Stripe rejects refunds on a disputed charge. Once the dispute is won the order is refundable again. GET /v1/refunds lists refunds of test purchases next to real ones, newest first. A test refund has livemode: false, provider: "test" and an id starting with re_test_. It moved no money and never counts toward revenue.

Orders (the read model)

An order (ord_...) is the record of a completed purchase or a paid subscription renewal. You don’t create orders directly — they appear when a checkout is paid, and again for each paid renewal of a subscription or payment plan. Orders are made of order items (ordi_...), one per price variant purchased, and carry a charge (ch_...) for the payment.

# List orders
curl https://api.crevio.co/v1/orders \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Retrieve one, inlining the customer and line items
curl "https://api.crevio.co/v1/orders/ord_abc123?expand=customer" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use the expand query param to inline related resources (e.g. customer) that otherwise appear as bare id strings. Individual line items are also retrievable directly via the order items endpoints.

The reliable signal that a sale is final is the order.paid webhook — fulfill purchases there rather than at checkout creation, since a created checkout isn’t yet a paid order.

Renewal orders

Each paid renewal is its own order with billing_reason: "subscription_cycle", the subscription id it renews, the purchase’s line_items and customer, and its own charge, amount and refunds. It has checkout: null and empty metadata. The order that started the subscription has billing_reason: "subscription_create", and one-time orders have null. Renewals send order.created and order.paid like any order, so a handler that fulfils on order.paid should skip subscription_cycle orders. See Subscription renewals.Refunding a renewal order returns that payment only. It doesn’t touch the subscription or the buyer’s access; cancel the subscription for that.

Shipping and billing addresses

An order carries the addresses the buyer entered at checkout as shipping_address and billing_address, each with name, line1, line2, city, state, postal_code and country (ISO 3166-1 alpha-2). Either is null when the checkout collected none. A shipping address is collected only when collect_shipping_address is on; a billing address only when Stripe asked the buyer for one, for example to calculate tax.

{
  "id": "ord_abc123",
  "object": "order",
  "shipping_address": {
    "name": "Jordan Lee",
    "line1": "500 Market St",
    "line2": "Apt 4",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "billing_address": null
}

A renewal order carries the addresses of the purchase that started its subscription. Both are a snapshot of what the buyer typed for that purchase, not the customer’s current address, so they stay correct for shipping even if the customer moves later. Because a webhook’s data.object is the API resource, order.created, order.paid and the refund events carry them too — a print-on-demand or fulfillment integration can place the shipment straight from the order.paid payload.

Next steps

Checkouts

Create the checkouts that produce orders and pay invoices.

Products & pricing

Configure subscription and payment-plan price variants.

Webhooks

Subscribe to order.paid, invoice.paid, refund.created, and more.

Commerce overview

See how subscriptions, invoices, and refunds fit the whole model.

Getting started

AI & agents

Core concepts

Integrations

Recipes

Subscriptions & billing

Subscriptions

List and retrieve

Change subscription state

Cancellation feedback

Discount an existing subscription

Invoices

Create an invoice

Pay an invoice

Void an invoice

Refunds

Full refund

Partial refund

Orders (the read model)

Renewal orders

Shipping and billing addresses

Next steps

Checkouts

Products & pricing

Webhooks

Commerce overview

​Subscriptions

​List and retrieve

​Change subscription state

​Cancellation feedback

​Discount an existing subscription

​Invoices

​Create an invoice

​Pay an invoice

​Void an invoice

​Refunds

​Full refund

​Partial refund

​Orders (the read model)

​Renewal orders

​Shipping and billing addresses

​Next steps

Checkouts

Products & pricing

Webhooks

Commerce overview

Subscriptions

List and retrieve

Change subscription state

Cancellation feedback

Discount an existing subscription

Invoices

Create an invoice

Pay an invoice

Void an invoice

Refunds

Full refund

Partial refund

Orders (the read model)

Renewal orders

Shipping and billing addresses

Next steps