Session Management
- Create a new booking session at the start of each user's checkout flow.
- Keep the session alive by making API calls within the 20-minute window.
- Handle
401 errors gracefully — prompt the user to restart their session.
Pricing
- Always display
full_price (face value + booking fee) to the end user.
- Never cache prices — always use the latest data from the API.
- Set
booking_fee within the min_booking_fee / max_booking_fee range.
Availability
- Availability is real-time. Seats/tickets can be sold out between search and reservation.
- Handle reservation failures gracefully — suggest alternative dates/sections.
Multi-Attraction Baskets
- Not all attractions can be purchased together. If you get error code
36, display a message and let the user complete transactions separately.
Polling (Async Flow Only)
- When polling transaction status, use exponential backoff (e.g., 2s, 4s, 8s...).
- Stop polling once the status is
PAID, FAILED, or REFUNDED.
- Not needed for the sync flow (
POST /v2/reservations/confirm) — the response is final.
Error Recovery
- On expired sessions, create a new session and guide the user back to attraction selection.