> ## 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.
# Subscriptions & billing
> Manage recurring revenue, invoices, and refunds — cancel/pause/resume subscriptions, bill with invoices, and return money on orders.
**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
```bash theme={null}
# 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` |
```bash theme={null}
# 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"
```
```typescript theme={null}
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
```bash theme={null}
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:
```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" }'
```
The returned checkout URL is what the customer uses to pay. See [Checkouts](/developer/guides/checkouts#paying-an-invoice).
### Void an invoice
To cancel an unpaid invoice:
```bash theme={null}
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
```bash theme={null}
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
```bash theme={null}
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.
```bash theme={null}
# 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
Create the checkouts that produce orders and pay invoices.
Configure subscription and payment-plan price variants.
Subscribe to `order.paid`, `invoice.paid`, `refund.created`, and more.
See how subscriptions, invoices, and refunds fit the whole model.