Billing & cadence
A subscription's cadence and billing direction determine when it bills and which period each invoice covers. These are computed by the billing engine — there is no public endpoint to call; you predict the behavior.
Cadence
A cadence is an interval unit × a count. There is no monthly / quarterly
enum — quarterly is month × 3, half-yearly month × 6, annual month × 12 (or
year × 1).
| Interval | Cadence |
|---|---|
day | Daily. |
week | Weekly. |
month | Monthly. Quarterly = month × 3; half-yearly = month × 6. |
year | Annual. Equivalent to month × 12. |
Advance vs. arrears
billingDirection (set at assign) decides where
in the period the charge sits:
| Direction | When the invoice is issued | Covers |
|---|---|---|
advance | at the start of the period | the period about to begin |
arrears | at the end of the period | the period just completed |
Next billing date
The engine tracks each schedule's nextBillingDate and a recurring job
seeks it: when the date is reached, an invoice is issued for that period and the
date advances by the cadence. A nextBillingDate far in the past (e.g. a
back-dated start) produces multiple catch-up invoices, one per elapsed
period, until the schedule is current.
Invoice date and due date
The invoice date is always the date the run issues it — a legal requirement,
not the period start. The payment due date is invoiceDate + paymentTerms
(the customer's terms). So an advance invoice issued on the 1st for July is
dated the 1st even though it covers the whole month ahead.
Send-offset (prebill)
Operators can configure a lead time so an advance invoice is issued a few days
before the period starts (prebill). This offset is operator-configured and not
a public API field; it shifts the issue date earlier but not the period it
covers.