Tirth API · Guide
Bookings and their lifecycle
A booking turns a quote into a puja or a yatra that Tirth performs. The pilgrim stays your customer: Tirth never creates a Tirth account for them and never markets to them.
Booking a quote
POST /v2/bookings needs the bookings:write scope and an Idempotency-Key.
| Field | What it is |
|---|---|
quote_id | A quote whose lock has not ended |
partner_reference | Your own reference for the order |
sankalp | For a puja: the names read in the sankalp, each with a gotra or null, up to 20, and how the family joins (join_as) |
travellers | For a package: each traveller's name and age_band, one with is_lead: true and their phone_e164 |
The lead traveller's phone is the yatra's contact. It is never sent in a webhook.
Your partner reference
- 1 to 64 characters from
A-Z a-z 0-9 _ -, such asORD-2026-000123. - Never an email or a phone number: a reference with
@or with a run of 10 digits is400, withfieldset topartner_reference. Soraju@exampleand9812345678are refused. - Unique for your company forever: using one again, even months later, is
409 partner_reference_taken.
Paying from credit
- An instant product is booked at once, and its
net_totalis taken from your credit. With ₹30,000 of credit, the booking of a quote whosenet_totalis 4,59,000 paise leaves 25,41,000 paise. - An on-request product is
requested: its credit and seats are held but not spent until Tirth decides, within 24 hours for a puja and 48 for a package. Accepted, it becomesbooked. Declined, or not decided in time, it becomesdeclinedand the held credit is given back to your credit, labelled "Released". - Credit that does not cover the booking is
402 credit_insufficient. Nothing is taken, and the quote's lock still stands.
The lifecycle
| Status | When |
|---|---|
requested | An on-request booking waits for Tirth's decision |
booked | Confirmed and paid from credit |
declined | Tirth did not accept an on-request booking |
assigned | Every service of the booking has its people |
scheduled | The time is set, with vouchers or pickup where there are any |
performed | The puja is done, or the yatra is over |
proof_shared | The checked proof is shared |
closed | 7 days after the proof is shared or the yatra ends, with no open case |
cancelled | The booking was cancelled |
declined, cancelled and closed are final. Every change of status sends a webhook and bumps the booking's version; a status that is passed over still sends its own webhook, in order.
Reading bookings
GET /v2/bookings/{id}: one booking, with its status and version, lines with the date and tithi, the money, the cancellation policy it was sold with, and the names or travellers. Never a phone number.GET /v2/bookings?partner_reference=ORD-2026-000123: find a booking by your reference.GET /v2/bookings?status=booked&updated_since=2026-11-30T18:30:00Z: the bookings whose status changed since a moment, newest first, a page at a time withcursor. Write the moment in UTC withZ, or encode the+of an offset as%2B.
These reads need the bookings:read scope. Another company's booking answers 404.
The change feed
Webhooks can be missed. The change feed lets you catch up: it lists every status change of your bookings, oldest first.
curl https://sandbox.api.tirth.com/v2/booking-changes \
-H "Authorization: Bearer $TIRTH_API_KEY"{
"items": [
{
"event_id": "evt_01JE5KD6F8H0K2M4P6R8T0V2X4",
"booking_id": "ord_01JE5KC5E7G9J1M3P5R7T9V1X3",
"partner_reference": "ORD-2026-000123",
"status": "assigned",
"version": 3,
"occurred_at": "2026-12-05T10:12:00+05:30"
}
],
"next_cursor": null,
"last_acked_event_id": null
}When you have stored the changes, acknowledge the last one. The next read starts after it:
curl https://sandbox.api.tirth.com/v2/booking-changes/ack \
-H "Authorization: Bearer $TIRTH_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "event_id": "evt_01JE5KD6F8H0K2M4P6R8T0V2X4" }'When a page is full, next_cursor is the event to read after: pass it as after to read on without acknowledging. It is null when there is nothing more for now.
Ignoring stale changes
Changes and webhooks can arrive out of order. Keep the highest version you have seen for each booking, and ignore anything with a lower one.
function apply(change, stored) {
if (stored && stored.version >= change.version) return stored;
return { status: change.status, version: change.version };
}Proof
GET /v2/bookings/{id}/proof lists a booking's proof: the puja video, photos or a courier's tracking. Each link is signed for your company and that booking, and works for 24 hours (links_valid_until_text); read the proof again for fresh links. A samuhik puja's video says the second the family's names are read. Proof never carries the names read in the sankalp.
