# 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`).

{/* @codegen subscription-cadence — generated by `pnpm docs:generate`; do not edit by hand */}

| Interval | Cadence |
|---|---|
| `day` | Daily. |
| `week` | Weekly. |
| `month` | Monthly. Quarterly = `month` × 3; half-yearly = `month` × 6. |
| `year` | Annual. Equivalent to `month` × 12. |

{/* @codegen-end subscription-cadence */}

## Advance vs. arrears

`billingDirection` (set at [assign](/guides/subscriptions/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.