Concepts

Credits and the ledger

Work with three separate customer balances, learn the order they are spent in, and see why every balance comes from an append-only, double-entry ledger.

A customer can hold three separate balances, and tmbilling spends them in a fixed order before it charges a card. Every balance comes from an append-only, double-entry ledger, so each one can explain itself.

The ledger

tmbilling keeps money in a double-entry, append-only ledger. Every movement writes a pair of entries, and nothing is ever updated or deleted. A balance is not a column tmbilling overwrites — it derives from the entries that produced it.

So a correction is a new, compensating entry rather than an edit. Voiding an invoice does not erase its postings. It reverses them, and both halves stay visible.

That costs a little at write time and buys you the thing that matters when a customer disputes a number: you can trace every figure back to what produced it.

Three balances, not one

Your customer's "credit" is three separate balances per currency, and they are not interchangeable.

Balance	Applied	Refundable	Where it comes from
Promotional credits	before tax	no	Goodwill, service credits, campaign grants. ₹100 of promotional credit removes ₹100 of taxable value, so the tax drops too. It was never money, so you cannot pay it back in cash.
Refundable credits	after tax	yes	A refundable credit note against a paid invoice. This was real money, so you can refund it to the card.
Excess payments	after tax	yes	Overpayments, payments removed from an invoice, and amounts you record ad hoc. Also real money.

Promotional credit reduces the amount tmbilling taxes. The other two reduce what is left to pay once tax is calculated. Treat all credit as one number and you get the tax figure wrong in exactly the cases a tax authority examines.

Application order on an invoice

discounts
  → promotional credits        (PRE-tax)
  → tax
  → refundable credits         (POST-tax)
  → excess payments            (POST-tax)
  → charge the card

Each step sees only what the previous one left. When credit covers an invoice completely, tmbilling posts it and marks it paid without calling a gateway.

Work with balances

GET/v1/businesses/{biz}/customers/{cus}/wallet

Returns all three balances, per currency.

POST/v1/businesses/{biz}/customers/{cus}/promotional_credits

Adds, deducts or sets promotional credit. Every movement emits an event, so your systems can react to a grant.

POST/v1/businesses/{biz}/customers/{cus}/record_excess_payment

Books money that arrived outside the normal flow — a bank transfer with no invoice reference — as excess credit, ready to apply.

POST/v1/businesses/{biz}/customers/{cus}/wallet/topup

Tops up a wallet. A paid top-up charges the card. A granted one is promotional. One endpoint writes to two very different balances, so select the type with care.

Credit notes

A credit note takes money back off an invoice. Its kind follows from whether the invoice was paid:

Invoice state	Kind	What you get
Unpaid	`adjustment`	Reduces the balance owed. Write-offs and unpaid downgrades use this.
Paid	`refundable`	Becomes refundable credit, which you can refund to the card or record as an offline refund.

A credit note moves through refund_due, refunded, adjusted and voided. tmbilling enforces total = allocated + refunded + available, so you cannot spend one twice or refund more than it is worth.

Voiding a credit note reverses it with compensating entries. tmbilling refuses once you have refunded or allocated it — in an append-only ledger you undo something by posting its opposite, not by removing it.

Edit this pageorReport an issue

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.

Tax

Configure taxable regions and their component rates, select inclusive or exclusive pricing, handle withholding and exemptions, and see what an invoice records.