Concepts

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.

An invoice records what your customer owes for a period. The billing clock generates most of them, and you can raise one by hand.

How tmbilling assembles one

The order is fixed:

assemble lines (recurring + prorations + usage + unbilled charges)
  → coupon discounts and promotional credits   (PRE-tax)
  → tax per line, plus withholding
  → optional round-off
  → refundable credits and excess payments     (POST-tax)
  → due date
  → ledger postings
  → collect

Discounts reduce the taxable amount. Credits do not. That is why the two kinds of credit sit on opposite sides of the tax step — see Credits and the ledger.

Statuses

Status	What it means
`pending`	Open and still collecting lines. Usage and charges are still landing on it, so it is not yet a demand for payment.
`posted`	Finalized. Lines, tax and totals are fixed.
`payment_due`	Posted, and owed — past its due date, or collection failed.
`not_paid`	Collection failed and dunning ran its course.
`paid`	Settled.
`voided`	Cancelled, with its ledger postings reversed by compensating entries.

An invoice under retry also carries a dunning_status, moving from in_progress to succeeded, exhausted or stopped. (success, the spelling before migration 0302, is still accepted on filters.)

Close a pending invoice

A pending invoice is how metered billing accumulates. Usage events and mid-cycle charges land on it through the period, and it becomes a finished document when you close it:

POST/v1/businesses/{biz}/invoices/{inv}/close

Closing applies discounts, tax and credits, sets the due date, posts the ledger entries and attempts collection. The billing clock closes invoices on schedule. Use this endpoint to close one early.

Run an operation on an invoice

Call	What it does
`POST /invoices/{inv}/collect`	Attempts collection now against the customer's payment method. `retry` is an alias — the "retry now" button in a dunning flow.
`POST /invoices/{inv}/pay`	Records an offline or manual payment such as a bank transfer or cheque, or simply marks it paid.
`POST /invoices/{inv}/apply_credits`	Applies the customer's refundable or excess credit to this invoice.
`POST /invoices/{inv}/void`	Cancels an open invoice, reverses its ledger postings and returns any coupon redemptions it consumed.
`POST /invoices/{inv}/regenerate`	Builds a fresh invoice for the same period after you void one. Use it to fix an invoice issued against wrong configuration.
`POST /invoices/{inv}/write_off`	Gives up on an unpaid invoice as bad debt, through an adjustment credit note so the ledger still explains where the money went.
`POST /invoices/{inv}/pause_dunning` · `stop_dunning`	Holds the retry schedule while your customer sorts out their card, or stops chasing entirely.

Edit an invoice after posting

You can change the operator-editable fields only: PO number, expected payment date, notes and the address snapshot.

PATCH/v1/businesses/{biz}/invoices/{inv}

Amounts are not among them. tmbilling does not change an issued document's totals — correct one with a credit note, which is a new document carrying its own reason. That way both sides of a dispute read the same trail.

Render an invoice

GET/v1/businesses/{biz}/invoices/{inv}/pdf

GET/v1/businesses/{biz}/invoices/{inv}/html

Send the PDF, or embed or print the HTML. Both carry your business's branding.

Issue a credit note

A credit note reduces what your customer owes, or gives money back. Its kind follows the invoice:

Against	Kind	What happens
An unpaid invoice	`adjustment`	Reduces the balance owed. Write-offs and unpaid downgrades use this.
A paid invoice	`refundable`	Becomes refundable credit on the customer's balance, which you can refund to the card or record as an offline refund.

POST/v1/businesses/{biz}/credit_notes

POST/v1/businesses/{biz}/credit_notes/{cn}/refund

tmbilling enforces total = allocated + refunded + available, so you cannot spend a credit note twice. Voiding one reverses it with compensating entries, because the ledger is append-only.

Raise a manual invoice

POST/v1/businesses/{biz}/invoices

Creates a one-off invoice with your own lines, for something that is not a subscription. It takes the same tax, credit and collection path as a generated one.

Edit this pageorReport an issue

Subscriptions

Follow a subscription through its statuses and terms, select one of the two endpoints that change items, and estimate every money-moving call before you run it.

Payments

Configure gateway accounts, learn how a charge is routed to one, handle 3-D Secure with payment intents, and read the record of every payment attempt.