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" });

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.

Orders (the read model)

An order (ord_...) is the record of a completed purchase. You don’t create orders directly — they appear when a checkout is paid. 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.

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.

​Subscriptions

​List and retrieve

​Change subscription state

​Invoices

​Create an invoice

​Pay an invoice

​Void an invoice

​Refunds

​Full refund

​Partial refund

​Orders (the read model)

​Next steps

Checkouts

Products & pricing

Webhooks

Commerce overview

Subscriptions

List and retrieve

Change subscription state

Invoices

Create an invoice

Pay an invoice

Void an invoice

Refunds

Full refund

Partial refund

Orders (the read model)

Next steps