Tirth API · Guide
Cancellations and changes
A booking carries the cancellation policy it was sold with. Later changes to a product's policy never reach a booking already made. Refunds go back to your credit.
Cancelling: quote first
GET /v2/bookings/{id}/cancellation-quote (scope bookings:cancel) works out what a cancellation would refund now, under the booking's own policy:
{
"booking_id": "ord_01JE5KC5E7G9J1M3P5R7T9V1X3",
"paid_paise": 459000,
"charge_bp": 2500,
"charge_paise": 114750,
"refund_paise": 344250,
"valid_until": "2026-12-04T15:05:00+05:30",
"valid_until_text": "3:05 PM IST, Fri 4 Dec 2026",
"quote_token": "…",
"policy_lines": ["…"]
}charge_bp is the share kept, in basis points (2500 is 25%). The quote holds until the earlier of 30 minutes and the policy's next band, and its quote_token is signed for your company.
Cancelling
POST /v2/bookings/{id}/cancellations (scope bookings:cancel, Idempotency-Key required):
curl https://sandbox.api.tirth.com/v2/bookings/ord_01JE5KC5E7G9J1M3P5R7T9V1X3/cancellations \
-H "Authorization: Bearer $TIRTH_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "quote_token": "…", "refund": "policy", "reason": "customer_request" }'| Field | What it is |
|---|---|
quote_token | The cancellation quote's token, to hold its refund. A token past its time is 410 quote_expired |
refund | policy (the default): what the policy gives. full: ask for a full refund where the policy gives less |
reason | customer_request, duplicate_booking, service_issue, travel_disruption or other |
- Inside the policy (
refund: "policy"), the cancellation is approved at once:200,status: "approved", andrefund_paisegoes back to your credit. Finance approves a refund above ₹50,000 before it is paid. - Asking for more than the policy gives (
refund: "full") goes to Tirth's review:202,status: "in_review", andrefund_paiseisnulluntil Tirth decides. - More than 10 cancellations by your company in an hour pauses automatic approval: further ones go to review.
- A booking can be cancelled only before its scheduled start: after it,
409 cancellation_closed. One already cancelled, or one that cannot be cancelled, is409 not_cancellable.
A cancelled booking moves to cancelled and sends its webhook.
Refunds
GET /v2/refunds and GET /v2/refunds/{id} (scope bookings:read) list the refunds to your credit: from cancellations, from declined on-request bookings ("Released"), and from cheaper changes. Refunds never go to the pilgrim from Tirth: your customer's refund is yours to make.
Changing a booking
Three kinds of change can be asked for:
change.kind | What changes |
|---|---|
date_change | A new date (new_date), with its departure, samuhik session or time where the product has them |
headcount | New travellers, and quantity for rooms, vehicles, families or groups |
swap | Another option of the same product (new_variant_id) |
POST /v2/bookings/{id}/amendment-quotes(scopebookings:write) prices the change at today's Agent net, with a 30-minute lock. Nothing is written. Itsdifference_paiseis the new total less the current one.POST /v2/bookings/{id}/amendments(Idempotency-Keyrequired) asks for it. Sendexpected_difference_paisefrom the amendment quote: if the price has moved since, the answer is412 price_changedand you quote again.
The change is proposed until Tirth's team makes it, then applied. A change that costs less is refunded to your credit when it is applied. A change that costs more is not made through an amendment (409 not_amendable): cancel and book again, since credit pays for a booking once.
{
"change": { "kind": "date_change", "new_date": "2026-12-19" },
"expected_difference_paise": 0
}