Subscriptions
A subscription holds many items: one line per price, each with a quantity. A plan, three add-ons and a metered line share one renewal date and one invoice.
Once you create it, the billing clock owns it. Renewal, invoice generation, collection and dunning happen without further calls from you.
Statuses
| Status | What it means |
|---|---|
future | You gave it a start date that has not arrived. |
in_trial | It is in its trial period. tmbilling charges nothing yet. |
active | It is billing normally. |
non_renewing | It runs to the end of the current term, then stops. You get this from "cancel at period end", and a subscription that runs out of billing cycles reaches it on its own. |
paused | tmbilling does not bill it while paused. |
cancelled | Terminal. |
payment_due
and dunning starts, while the subscription can stay active throughout.You configure what happens when the retries run out — it may cancel, and it may not. The
subscription carries counters for what is owed rather than a status that conflates money with
access. See Failed payments and dunning.Terms
A subscription has a current term: the period you bill it for. At the end of each term tmbilling rolls it forward and raises the invoice for the period just begun.
Recurring lines bill in advance. Usage bills in arrears, for the period that just closed.
| Field | Type | What it does |
|---|---|---|
trial_days | integer | Starts the subscription in_trial. tmbilling makes the first charge when the trial ends. |
start_date | ISO-8601 | Backdates or future-dates the period start. A future date gives you a future subscription. |
billing_anchor | ISO-8601 | Fixes the first period end, so you can align a subscription to a calendar billing date instead of its signup date. |
remaining_billing_cycles | integer | Sets a fixed number of renewals. At zero the subscription becomes non_renewing rather than cancelled, which matters to your customer's access. |
/v1/businesses/{biz}/subscriptions/{sub}/change_term_endMoves the current term's end boundary, when you need the next invoice on a specific day.
Change the items
Two endpoints change items, and picking the wrong one is the usual mistake:
| Endpoint | You send | tmbilling does |
|---|---|---|
POST /subscriptions/{sub}/change | a delta | Applies your additions, removals and quantity changes, and leaves everything you don't mention alone. |
POST /subscriptions/{sub}/update_for_items | the complete item list | Makes the subscription match your list, removing anything absent from it. |
Both prorate immediately. tmbilling credits the unused portion of what you removed, charges the new item pro rata, and writes both as invoice lines and ledger entries.
Estimate before you charge
Every money-moving call has a dry run that returns the real numbers and moves nothing:
| Estimate | Tells you |
|---|---|
POST /customers/{cus}/subscription_estimate | What the first invoice will be |
POST /subscriptions/{sub}/estimate | What a change, addition or removal will cost |
POST /subscriptions/{sub}/cancel_estimate | What cancelling does to the money |
POST /subscriptions/{sub}/reactivate_estimate | What reactivating will invoice |
GET /subscriptions/{sub}/renewal_estimate | The next renewal amount |
Show one to your customer before you charge them.
Schedule a change instead of applying it
Anything dated can wait:
/v1/businesses/{biz}/subscriptions/{sub}/scheduleSchedules a future-dated cancel, pause, resume or change.
A pending schedule is a real object. List it, show it to your customer, and withdraw it if they change their mind:
/v1/businesses/{biz}/subscriptions/{sub}/scheduled_changes/v1/businesses/{biz}/scheduled_changes/{sch}Cancel, pause and resume
Each of these takes a full option set rather than a single boolean, because each raises the same questions: what happens to unbilled charges, to the outstanding balance and to refundable credit, and what reason to record.
/v1/businesses/{biz}/subscriptions/{sub}/cancel/v1/businesses/{biz}/subscriptions/{sub}/pause/v1/businesses/{biz}/subscriptions/{sub}/resume/v1/businesses/{biz}/subscriptions/{sub}/reactivateA resume inside the paid term keeps that term and charges nothing. A resume after it ends starts
a new term at the resume and always bills it: charges_handling is invoice_immediately or
add_to_unbilled_charges, and an omitted value takes the business's
pause_config.charges_on_resume (default invoice_immediately. next_renewal is a deprecated alias of add_to_unbilled_charges.). API, portal and scheduled resumes follow the same rule.
reactivate both clears a pending cancellation and restarts a subscription that already ended.
Run the estimate to see which one you are about to pay for.
Add a mid-cycle charge
/v1/businesses/{biz}/subscriptions/{sub}/chargesAdds a one-off charge. Invoice it immediately, or fold it into the next renewal.
Deferred charges wait as unbilled charges until tmbilling sweeps them into the next invoice:
/v1/businesses/{biz}/subscriptions/{sub}/unbilled_chargesRelated
Customers
Create the customer who pays, with the currency and address fields that tax depends on, saved payment methods with a backup role, and three separate balances.
Invoices
Learn how Two Minute Billing builds an invoice, the statuses it moves through, and every operation you can run on an invoice after the billing clock raises it.