Tirth API · Guide
Prepaid credit
On the Book tier, bookings are paid from credit your company adds in advance. The balance never goes below zero: a booking that it does not cover is refused with 402 credit_insufficient, and nothing is taken.
Topping up
Credit is added by bank transfer, NEFT, RTGS, IMPS or UPI, from your company's verified business account. Then tell Tirth about the transfer:
curl https://sandbox.api.tirth.com/v2/credit/top-ups \
-H "Authorization: Bearer $TIRTH_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "amount_paise": 2500000, "reference": "UTR123456789" }'POST /v2/credit/top-upsneeds thecredit:topupscope and anIdempotency-Key.referenceis the UTR or reference your bank gave the transfer.- The top-up answers
pendingwith what happens next. The credit is added only when Tirth's finance team matches the transfer on the bank statement; then it ispaid. - Today the first top-up is at least ₹25,000, and each later one at least ₹10,000.
- Transfers told to Tirth and not yet matched show in
GET /v2/creditaswaiting_for_verification_paise.
Lots
Each top-up opens a lot of its own. Bookings use the oldest open lot first.
| Day of a lot | What happens |
|---|---|
| Day 300 | Your company's admins are reminded of the unused part |
| Day 360 | The unused part leaves the credit and is refunded to the account that funded it |
For example, with top-ups of ₹25,000 on 1 Mar 2027 and ₹10,000 on 1 May 2027, a booking of ₹8,000 is taken from the 1 Mar lot. That lot's reminder is on Sun 26 Dec 2027, and its unused part is refunded on Thu 24 Feb 2028.
Credit given back to you, such as a cancellation's refund or a released on-request hold, opens a new lot of its own, counted from the day it comes back.
Reading your credit
| Call | Scope | What it answers |
|---|---|---|
GET /v2/credit | credit:read | The balance, your low-balance alert, the open lots with their expires_on, and transfers waiting to be matched |
GET /v2/credit/transactions | credit:read | Every movement, newest first: top-ups, bookings, holds for requests, releases, refunds and expired lots, each with its lots |
GET /v2/credit/statements/{yyyy-mm} | credit:read | A month that has ended in India, as CSV, from its opening balance to its closing one |
GET /v2/invoices | invoices:read | The GST documents Tirth issued to your company |
A month's statement is made by the 5th of the next month. The current month is 404 until it ends.
Refunds of credit
Credit is refunded only to the account that funded it. Changing that account needs a fresh sign-in code, a check by Tirth's finance team, and a 7-day hold.
In the sandbox
Each company starts with ₹1,00,000 of test credit in the sandbox, labelled "Test credit". It has its own lot and expires at day 360 like any other. Test credit is never real money, and production never sees it.
