Tirth API · Guide
The sandbox
The sandbox is a separate Tirth API to build and test against, at https://sandbox.api.tirth.com/v2. It runs the same code as production, on its own database, with nothing real in it.
What is in it
- Test keys only. The sandbox takes
tirth_test_sk_…keys and refuses live keys with401 unauthenticated; production refuses test keys the same way. - Fixture products. Sample pujas, an on-request puja, a package on fixed departures and an add-on, each titled "Sample", with fake prices.
- Test credit. Each company starts with ₹1,00,000 of test credit, labelled "Test credit" in its transactions. It is never real money.
- Simulated fulfilment. Nobody performs a sandbox puja: you move bookings through their stages yourself, and each stage sends its webhook as production would.
- Half the limits. Every rate limit is half the live figure. See Rate limits.
Moving a booking along
POST /v2/sandbox/bookings/{id}/advance (scope bookings:write) moves one of your sandbox bookings one stage on:
booked → assigned → scheduled → performed → proof_shared
curl -X POST https://sandbox.api.tirth.com/v2/sandbox/bookings/ord_01JE5KC5E7G9J1M3P5R7T9V1X3/advance \
-H "Authorization: Bearer $TIRTH_API_KEY"{
"booking_id": "ord_01JE5KC5E7G9J1M3P5R7T9V1X3",
"previous_status": "booked",
"status": "assigned",
"version": 2
}Each step sends the stage's webhook with the booking's new version. A booking still requested, already at proof_shared, or ended has no next stage: 409 not_advanceable. Production answers this route with 404 sandbox_only.
Scenarios
Send the header Tirth-Sandbox-Scenario to make the sandbox answer as it would in a case that is hard to set up. Production ignores the header.
| Scenario | On | What happens |
|---|---|---|
credit_insufficient | POST /v2/bookings | 402 credit_insufficient. Nothing is taken, and the quote's lock still stands |
quote_expired | POST /v2/bookings | 410 quote_expired, as a booking after the lock |
on_request_accept | POST /v2/bookings | An on-request booking is accepted at once: requested, then booked |
on_request_decline | POST /v2/bookings | An on-request booking is declined at once, and its held credit is "Released" |
price_changed | POST /v2/bookings/{id}/amendments | 412 price_changed, as when the change's price moved |
Any other value is 400 validation_failed, with field set to Tirth-Sandbox-Scenario.
curl https://sandbox.api.tirth.com/v2/bookings \
-H "Authorization: Bearer $TIRTH_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Tirth-Sandbox-Scenario: on_request_decline" \
-d '{
"quote_id": "qt_01JE5K9A4C6E8G0J2M4P6R8T0V",
"partner_reference": "TEST-DECLINE-1",
"sankalp": { "names": [{ "name": "Test Name", "gotra": null }] }
}'A test run worth making
- Quote and book an instant puja; check your credit went down by the quote's
net_total. - Advance it to
proof_shared, and check your endpoint received each webhook, inversionorder, with a valid signature. - Read the change feed and acknowledge it.
- Book again with
credit_insufficient, then withquote_expired, and check your system shows each error to your team. - Book an on-request product with
on_request_acceptand withon_request_decline. - Cancel a booking with a cancellation quote, and find the refund in
GET /v2/refunds.
