---
title: "Credits and the ledger"
description: "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."
canonical_url: "https://twominutebilling.com/help/developers/concepts/credits"
---
# 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.

<table>
<thead>
  <tr>
    <th>
      Balance
    </th>
    
    <th>
      Applied
    </th>
    
    <th>
      Refundable
    </th>
    
    <th>
      Where it comes from
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Promotional credits
    </td>
    
    <td>
      before tax
    </td>
    
    <td>
      no
    </td>
    
    <td>
      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.
    </td>
  </tr>
  
  <tr>
    <td>
      Refundable credits
    </td>
    
    <td>
      after tax
    </td>
    
    <td>
      yes
    </td>
    
    <td>
      A refundable credit note against a paid invoice. This was real money, so you can refund it to the card.
    </td>
  </tr>
  
  <tr>
    <td>
      Excess payments
    </td>
    
    <td>
      after tax
    </td>
    
    <td>
      yes
    </td>
    
    <td>
      Overpayments, payments removed from an invoice, and amounts you record ad hoc. Also real money.
    </td>
  </tr>
</tbody>
</table>

<warning title="The pre-tax and post-tax split is what keeps your tax right">

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.

</warning>

## Application order on an invoice

```text
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

<endpoint method="GET" path="/v1/businesses/{biz}/customers/{cus}/wallet">



</endpoint>

Returns all three balances, per currency.

<endpoint method="POST" path="/v1/businesses/{biz}/customers/{cus}/promotional_credits">



</endpoint>

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

<endpoint method="POST" path="/v1/businesses/{biz}/customers/{cus}/record_excess_payment">



</endpoint>

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

<endpoint method="POST" path="/v1/businesses/{biz}/customers/{cus}/wallet/topup">



</endpoint>

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:

<table>
<thead>
  <tr>
    <th>
      Invoice state
    </th>
    
    <th>
      Kind
    </th>
    
    <th>
      What you get
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Unpaid
    </td>
    
    <td>
      <code>
        adjustment
      </code>
    </td>
    
    <td>
      Reduces the balance owed. Write-offs and unpaid downgrades use this.
    </td>
  </tr>
  
  <tr>
    <td>
      Paid
    </td>
    
    <td>
      <code>
        refundable
      </code>
    </td>
    
    <td>
      Becomes refundable credit, which you can refund to the card or record as an offline refund.
    </td>
  </tr>
</tbody>
</table>

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.

## Related

- [Invoices](https://twominutebilling.com/help/developers/concepts/invoices)
- [Security and the append-only ledger](https://twominutebilling.com/security)


## Sitemap

See the full [sitemap](https://twominutebilling.com/sitemap.md) for all pages.