Billing & cadence
A subscription's cadence and billing direction determine when it bills and which period each invoice covers. The billing engine computes both; there is no public endpoint to call, so predict the behavior from the rules on this page.
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. When a recurring job
reaches the date, it issues an invoice for that period and advances the date
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.
The subscription resource exposes this as effectiveNextBillingDate: the date
the next invoice will be created. It is an invoicing-schedule marker, not a
payment marker; for what the customer has paid for, read
paidThroughDate.
Payment timing never moves the schedule
The schedule advances when an invoice is issued, never when it is paid. A
charge that clears late — on the fifth automatic retry, through a
manual retry, or by
a bank transfer weeks after the due date — settles exactly the period its
invoice stated. Neither the covered period nor nextBillingDate shifts, so a
late payment never causes a gap, an overlap, or a delayed next cycle.
Paid-through date
paidThroughDate is the first day the customer has not yet paid for. It is the
end of the contiguous run of settled service periods starting at the earliest
billed period, so an unpaid period caps the value instead of being skipped: with
January settled, February unpaid and March settled, the subscription is paid
through February's start, not April. It is null when the earliest billed
period is not settled, and it counts only genuine service-coverage periods — a
one-off fee, a surcharge, or a discount line never advances it.
It appears on the subscription resource (see the API Reference) and on
the subscription.payment_succeeded webhook payload, where it reflects the
period the cleared charge covered.
With advance billing and no send offset, a current subscription's
paidThroughDate equals effectiveNextBillingDate once the latest invoice is
paid: the paid period runs up to the next invoice. Under
prebill the two diverge — effectiveNextBillingDate
surfaces the earlier send date while paidThroughDate stays on the period
boundary, so an invoice covering through June 1 can sit beside a next-billing
date of May 22. With arrears billing paidThroughDate trails one period
behind, because payment covers completed periods. A paidThroughDate in the
past on an awaiting_payment subscription means an issued invoice is unpaid
and the dunning flow in
Card payments is
running.
Invoice date and due date
The invoice date is the date the run issues the invoice — a legal
requirement — never the period start. The due date is
invoiceDate + paymentTerms (the customer's payment terms). 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). The offset is not a public API field;
it shifts the issue date earlier, not the period the invoice covers.