Preview the next invoice for a customer (Stripe-equivalent)
const url = 'http://localhost:8080/v1/invoices/create_preview';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"customer_id":"example","subscription_id":"example","period":{"from":"2026-04-15T12:00:00Z","to":"2026-04-15T12:00:00Z"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:8080/v1/invoices/create_preview \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "customer_id": "example", "subscription_id": "example", "period": { "from": "2026-04-15T12:00:00Z", "to": "2026-04-15T12:00:00Z" } }'Answers “what is my next bill going to look like?” from the usage
recorded so far. Without period, the preview mirrors the cycle
close for the subscription’s current period: base fees prorate for
a short first period and per segment after a mid-period item add,
quantity change, plan swap or removal, and each meter’s usage counts
only while a plan carrying it was on the subscription. For a
trialing subscription it is the first invoice after the trial: the
trial-end invoice when a plan bills in advance, otherwise the close
of the first paid period, prorated the same way. With an
explicit period, it is a flat estimate over that window and warns
when a mid-period change makes the invoice differ. Composes across customer / subscription / pricing;
registered as a sibling of /v1/invoices (chi picks the more
specific pattern, otherwise /{id} would capture
create_preview as an invoice ID).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Makes the call safe to retry. Send a unique value (a UUID works) and
the same value on every retry. For 24 hours, a repeat with the same
key, method, path and body gets the first response again, with an
Idempotent-Replayed: true header, instead of running again. The
error cases are in docs/api-surface.md. The usage routes do not take
it: each usage event carries its own idempotency_key.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Customer to preview the invoice for.
Optional. Defaults to the customer’s primary active subscription if not supplied.
Optional explicit window. Both bounds must be supplied together; partial windows are rejected. Defaults to the resolved subscription’s current cycle.
object
Example generated
{ "customer_id": "example", "subscription_id": "example", "period": { "from": "2026-04-15T12:00:00Z", "to": "2026-04-15T12:00:00Z" }}Responses
Section titled “Responses”Preview result
A dry-run invoice built from the usage recorded so far. Nothing is saved.
object
The names of the subscription’s plans, comma-separated.
object
On a usage line, the plan price that priced it.
On a usage line, the labels its price takes. Absent for a price that takes every event.
object
Exact quantity as a decimal string.
One total per currency on the lines.
object
Ways the real invoice can differ from this preview.
Example
{ "lines": [ { "line_type": "base_fee", "pricing_mode": "per_unit" } ]}Invalid request body
object
object
One of invalid_request_error, authentication_error,
rate_limit_error or api_error. Every error the API
answers has this shape, including an unknown path (404,
code route_not_found) and a method the path does not take
(405, code method_not_allowed, with an Allow header).
The few exceptions are listed in docs/api-surface.md.
The request field the error is about. Sent only when the error
names one. A request body may hold only the fields its
operation lists, spelled and cased as listed: any other
field, or one the server sets (such as id), is refused
with 422 and param naming it. An operation with no request body lists no fields: send
no body, {} or null. The Stripe and Postmark webhooks and
the LiteLLM callback take their sender’s body as it comes.
Example
{ "error": { "type": "invalid_request_error" }}Customer or subscription not found
object
object
One of invalid_request_error, authentication_error,
rate_limit_error or api_error. Every error the API
answers has this shape, including an unknown path (404,
code route_not_found) and a method the path does not take
(405, code method_not_allowed, with an Allow header).
The few exceptions are listed in docs/api-surface.md.
The request field the error is about. Sent only when the error
names one. A request body may hold only the fields its
operation lists, spelled and cased as listed: any other
field, or one the server sets (such as id), is refused
with 422 and param naming it. An operation with no request body lists no fields: send
no body, {} or null. The Stripe and Postmark webhooks and
the LiteLLM callback take their sender’s body as it comes.
Example
{ "error": { "type": "invalid_request_error" }}Validation error (missing customer_id, partial period, no active sub, …)
object
object
One of invalid_request_error, authentication_error,
rate_limit_error or api_error. Every error the API
answers has this shape, including an unknown path (404,
code route_not_found) and a method the path does not take
(405, code method_not_allowed, with an Allow header).
The few exceptions are listed in docs/api-surface.md.
The request field the error is about. Sent only when the error
names one. A request body may hold only the fields its
operation lists, spelled and cased as listed: any other
field, or one the server sets (such as id), is refused
with 422 and param naming it. An operation with no request body lists no fields: send
no body, {} or null. The Stripe and Postmark webhooks and
the LiteLLM callback take their sender’s body as it comes.
Example
{ "error": { "type": "invalid_request_error" }}