Invoices

An invoice (inv_…) is a statement for one billing cycle. Most invoices are created automatically by the billing engine on each renewal; you can also create one-off draft invoices via the API.

Invoice status

Status	Meaning
`draft`	Editable, not yet finalized.
`open`	Finalized and awaiting payment from the wallet.
`paid`	Settled — the wallet was debited.
`void`	Canceled; never to be paid.

The automatic path

On each cycle the worker generates an open invoice and attempts to debit the wallet:

Wallet covers it → invoice paid, invoice.paid event/webhook fires.
Wallet short → invoice stays open, the subscription goes past_due, and invoice.payment_failed fires. Trile retries after a top-up.

You don’t call anything for this — just listen for the events.

Listing & retrieving

# List, filtered by status (cursor paginated)
curl "$TRILE_API/v1/invoices?status=paid&limit=50" -H "x-api-key: $TRILE_KEY"

# Retrieve one
curl "$TRILE_API/v1/invoices/inv_01ARZ3..." -H "x-api-key: $TRILE_KEY"

# Timeline of what happened to an invoice (bare array, oldest first)
curl "$TRILE_API/v1/invoices/inv_01ARZ3.../events" -H "x-api-key: $TRILE_KEY"

One-off / manual invoices

You can create a draft invoice scoped to a subscription, then finalize and send it:

# 1. Create a draft
curl -X POST "$TRILE_API/v1/invoices" \
  -H "x-api-key: $TRILE_KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "subscriptionId": "sub_01ARZ3...", "...": "line items" }'

# 2. Finalize & email it to the customer (draft → open)
curl -X POST "$TRILE_API/v1/invoices/inv_01ARZ3.../send" -H "x-api-key: $TRILE_KEY"

PATCH /v1/invoices/:id transitions status for the editable cases (e.g. void). An invoice that’s already finalized returns invoice_not_editable for edits that don’t apply.