Tirth API · Guide
Quotes and seat holds
A quote is the price of one selection for your company, ready to book. It is the only place the API gives an exact price: the catalogue's reference_price is tirth.com's starting price, for reference only.
Asking for a quote
POST /v2/quotes takes what to price:
| Field | What it is |
|---|---|
variant_id | The option chosen, from the product's variants |
service_date | The date, YYYY-MM-DD |
puja_event_id | A samuhik puja's session, from GET /v2/samuhik-pujas/{id}/sessions |
departure_id | A package's fixed departure, from GET /v2/packages/{id}/departures |
slot_id | A time, for a product that sells times |
travellers | Who is counted: adults, child_with_bed, child_without_bed and infant for a package; people for anything else |
quantity | Rooms, vehicles, families or groups, for a product priced per one of those. Default 1 |
add_ons | Up to 30 add-ons, each { "add_on_id": "ad_…", "quantity": 2 }, each named once |
hold_seats | true to hold seats on a samuhik session or a departure while the price is locked |
The Idempotency-Key is optional on quotes.
The price
The price is the Tirth Agent net price for the same selection: the API has no prices of its own. Every amount is in integer paise.
| Field | What it is |
|---|---|
net_total | What your credit pays, GST included |
net_amount | net_total without Tirth's GST |
tirth_gst | Tirth's GST on it |
reference_retail_price | What tirth.com charges for the same selection, for your own price display |
lines | The same figures per line, with the product, variant, dates and travellers |
For example, a net_total of 4,59,000 paise splits into a net_amount of 4,37,143 and tirth_gst of 21,857 (5%, rounded half up), beside a reference_retail_price of 5,10,000.
confirmation says how the booking will be confirmed: instant is booked at once, and on_request waits for Tirth to accept, within decision_within_hours (24 for a puja, 48 for a package).
The 30-minute lock
A quote locks its price for 30 minutes, to an absolute time in India:
{
"price_locked_until": "2026-12-04T14:35:00+05:30",
"price_locked_until_text": "2:35 PM IST, Fri 4 Dec 2026"
}A quote made at 2:05 PM IST on Fri 4 Dec 2026 holds until 2:35 PM IST. Show your customer the _text as it is, a time and a date, rather than the minutes that remain.
- The lock covers the price only. Availability is checked again when you book.
- Booking after the lock is
410 quote_expired: ask for a new quote. A booking at 2:36 PM on that quote is refused. - One quote makes one booking. A second booking with the same
quote_idis409 quote_used. 402 credit_insufficientkeeps the lock. Add credit and book again before it ends.
Seat holds
With "hold_seats": true on a samuhik session or a package departure, the quote also holds the seats until the lock ends. The quote's hold says how many seats, and until when, with its own held_until_text.
| Limit | Value |
|---|---|
| Open seats per company | 50, held or requested |
| All API companies together | At most 20% of a departure's remaining seats |
| On Amrit Snan dates | A hold lasts 10 minutes, and at most 20 seats per company per date |
- A hold over any cap is refused whole, with
409 hold_refused: holds are never partial. When 40 of a departure's seats are still open, all API companies may hold 8 between them: if one holds 6, another asking for 4 is refused. - A new quote for the same product and date releases your older hold on it.
- Requested bookings count toward the caps.
- If fewer than 1 in 5 of your holds became bookings over 24 hours, holds are switched off for your company until Tirth reviews them: quotes asking for holds are then
409 holds_disabled.
Quote sweeps
More than 30 different date or group-size quotes for one product in an hour stop quotes on that product for that key for an hour, with 429 quotes_blocked and Retry-After. Quote what your customer is choosing, not every combination.
In Node
const response = await fetch('https://sandbox.api.tirth.com/v2/quotes', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.TIRTH_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
variant_id: 'var_01JE5K7R2M8Q4T6V9X3B0C1D3G',
service_date: '2026-12-12',
puja_event_id: 'ss_01JE5KB2D4F6H8K0M2P4R6T8V0',
travellers: { people: 4 },
hold_seats: true,
}),
});
const quote = await response.json();
console.log(quote.net_total, quote.price_locked_until_text, quote.hold?.held_until_text);