Bookings and holds

A booking starts as a hold on the places the traveller chose, and checkout turns the hold into a booking. Every booking has a reference like TP-4HZQ-8MNE, unique across tourpingo and never reused.

The states

status	Meaning	What moves it on
on_hold	Places held for 15 minutes; nothing is booked yet.	Checkout, or time running out.
pending	Booked, waiting for the seller to confirm, or for the payment.	The seller confirms or declines; the payment arrives; or it expires.
confirmed	Booked and confirmed: the traveller gets a voucher.	The trip ends, or someone cancels.
completed	The trip has ended.	Nothing; only these can be reviewed.
cancelled	Cancelled by the traveller or the seller, with the refund the policy gave.	Nothing.
rejected	The seller declined it. The traveller is refunded in full.	Nothing.
expired	A hold that ran out, or a pending booking nobody acted on.	Nothing.

Holds

POST /v1/public/holds prices the selection again, as a quote would, and holds its places for 15 minutes (hold_expires_at). Held places count as taken on the calendar. When the hold runs out it becomes expired and the places go back on sale; checking it out then is refused with HoldExpired.

An option the seller confirms by hand (capacity_mode on_request) takes no hold: checkout books it straight away as pending, holding no places until the seller finds one.

Checkout

POST /v1/public/checkout turns a hold into a booking with the lead traveller’s details:

• confirmed at once when the option confirms instantly and nothing must be paid first, for example when the traveller pays on the day.
• pending when the seller confirms by hand (confirmation manual), or when a bank transfer or payment link must arrive first.

The price lines, the cancellation policy, the exchange rate and the trip as described are kept with the booking as they were sold, and never change afterwards.

Pending doesn’t last

• A booking waiting for the seller expires 48 hours after it was made, or at the start’s booking cutoff if that comes first (pending_expires_at), and the traveller is refunded.
• A booking waiting for its payment expires when the payment is due (payment.due_at): 7 days for a bank transfer and 72 hours for a payment link, by default, and never later than 48 hours before the start.

Following a booking

Webhooks, which will tell your site when a booking is confirmed or cancelled, are coming with issue #522. Until then, read the booking again when you need its status, as managing a booking shows.