Booking Flow

Understanding how bookings work in the YGO API is essential for building a complete travel booking experience. This guide explains the booking lifecycle, status transitions, and the shopping cart pattern that powers flexible customer experiences.

What is a Booking?

A booking represents a customer's travel reservation in the YGO system. Each booking is built around a main trip product (hotel-only, hotel+flight package, or pre-bundled trip) and can include additional items like activities and transfers added in a shopping cart fashion.

Every booking includes:

Trip Details - The main product (hotel, hotel+flight, or trip) with dates, destination, and pricing

Items - Additional products like activities and transfers added to enhance the trip

Travelers - Guest information (names, ages, types)

Contact Information - Lead traveler details for communication

Status - Current state in the booking lifecycle

Pricing - Total cost including all items and any discounts

Payment Information - Payment method, transaction IDs, invoice details

Each booking has a unique 8-character alphanumeric ID (e.g., A1B2C3D4) that remains constant throughout its lifecycle.

The Shopping Cart Pattern

Open Bookings as Shopping Carts

When a customer first selects a trip product, the system creates an open booking—essentially a shopping cart that persists across sessions. This open booking allows customers to:

Browse and add activities to their trip

Add airport transfers or other services

Update traveler information gradually

Return later to complete their booking

Modify their selections before payment

Key characteristics of open bookings:

Status: open

Persistent: Stored in the database, not just in-memory

One per product per user: Each user can have only one open booking per trip product

Idempotent: Calling getOpenBooking multiple times returns the same booking

Flexible: Can be updated via saveOpenBooking until payment

Building a Trip

The typical flow for building a booking:

Customer searches for packages → Finds a hotel+flight package they like

System creates open booking → Calls getOpenBooking (creates if doesn't exist)

Customer adds activities → Updates booking via saveOpenBooking with new items

Customer adds transfers → Updates booking again with transfer items

Customer enters traveler details → Updates booking with contact information

Customer proceeds to payment → Updates status to trigger workflows

TIP

Shopping Cart Analogy

Think of an open booking like an e-commerce shopping cart:

Main trip product = Featured item in cart

Activities/transfers = Additional items added to cart

Customer can add, remove, modify until checkout

Cart persists across browser sessions

Checkout = Payment triggers fulfillment

Booking Lifecycle and Statuses

Bookings progress through various statuses as they move from creation to completion. Understanding these statuses helps you build robust booking flows.

Status Overview

Status	Description	User-Facing	Triggers Workflows
`open`	Shopping cart (unpaid)	"In Progress"	No
`payment_pending`	Payment initiated but not confirmed	"Processing Payment"	No
`paid`	Payment successful	"Paid"	Yes - Books with suppliers
`booked`	Confirmed with all suppliers	"Confirmed"	No
`confirmed`	Booking confirmed to customer	"Confirmed"	No
`completed`	Trip finished	"Completed"	No
`cancelled`	Booking cancelled	"Cancelled"	May trigger cancellations
`refunded`	Payment refunded	"Refunded"	No
`payment_failed`	Payment processing failed	"Payment Failed"	No

Status Transitions

open → payment_pending → paid → booked → confirmed → completed
  ↓           ↓           ↓        ↓         ↓
cancelled ← ← ← ← ← ← ← ← ← ← ← ← ← ← (can cancel from most states)
  ↓
refunded (after cancellation)

Important rules:

✅ Status changes must move forward in the lifecycle

❌ Cannot transition back to open once payment begins

✅ Can cancel from most states (except completed or refunded)

Critical Status: `paid`

When a booking transitions to paid status, the system automatically triggers critical workflows:

Automatic Supplier Bookings:

Activities → Booked with Musement

Packages → Booked with Peakwork

Transfers → Booked with Exfinity

System Synchronization:

Status changes synced to connected midoffice systems

Supplier system updates (behavior depends on integrations)

Booking confirmation workflows triggered

Items marked for manual booking (BookManually=true) or requiring pickup selection (PickupRequired=true) are skipped during automatic booking.

WARNING

Setting Status to paid = Real Bookings

When you transition a booking from open to paid, the system immediately begins booking with live suppliers. This creates real reservations that may incur charges and cancellation fees.

Always:

Verify payment succeeded before setting status to paid

Call saveOpenBooking with checkBeforePayment=true before payment to validate availability and pricing

Handle failed supplier bookings gracefully

Common Booking Workflows

Workflow 1: Complete Booking Flow

Workflow 2: Retrieve Booking History

Workflow 3: Retrieve Single Booking

Which Endpoint to Use?

`getOpenBooking`

Use when: Creating or retrieving a shopping cart

✅ Customer starts booking a trip

✅ Customer returns to continue an incomplete booking

✅ Building a persistent shopping cart experience

✅ Need to check if user already has an open booking for this product

Key behavior: Idempotent - returns existing open booking or creates new one

`saveOpenBooking`

Use when: Updating booking details before payment

✅ Customer adds/removes activities or transfers

✅ Customer updates traveler information

✅ Customer changes contact details

✅ Validating availability before payment (checkBeforePayment=true)

Key behavior: Updates only Details object, validates ownership, cleans invalid items

`saveBookingStatus`

Use when: Transitioning booking through lifecycle states

✅ Payment succeeds → Set to paid (triggers supplier bookings)

✅ All suppliers confirm → Set to booked

✅ Confirming to customer → Set to confirmed

✅ Cancelling booking → Set to cancelled

Key behavior: Triggers automated workflows, cannot revert to open, syncs to external systems

`listBookings`

Use when: Displaying booking history or lists

✅ Showing "My Bookings" page

✅ Filtering by status (upcoming trips, past trips)

✅ Building admin dashboards

✅ Implementing pagination for many bookings

Key behavior: Returns array of bookings matching filters, supports sorting and pagination

`getBooking`

Use when: Retrieving a specific booking by ID

✅ Displaying booking confirmation page

✅ Customer clicks on a specific booking from list

✅ Retrieving booking details for modifications

✅ Showing booking to customer service

Key behavior: Returns single complete booking, validates ownership

Best Practices

DO:

Create open bookings early in the customer journey

Validate with checkBeforePayment=true before accepting payment

Only set status to paid after payment confirmation

Handle supplier booking failures gracefully

Keep the UI in sync with booking status

Use listBookings with filters for efficient queries

DON'T:

Set status to paid before payment succeeds

Skip the checkBeforePayment validation step

Try to revert status back to open after payment

Create multiple open bookings for the same product/user

Expose internal status names directly to customers

Call saveOpenBooking on bookings that aren't open

Error Handling

Common Scenarios

Booking Not Found:

{
  "Data": null,
  "Error": {
    "Code": "NOT_FOUND",
    "Message": "Booking not found"
  }
}

Possible causes:

Booking ID doesn't exist

Booking belongs to different user

Typo in booking ID

Cannot Revert Status:

{
  "Data": null,
  "Error": {
    "Code": "BAD_REQUEST",
    "Message": "Cannot revert booking status back to 'open'"
  }
}

Possible causes:

Trying to set paid booking back to open

Invalid status transition

Supplier Booking Failed:

{
  "Data": null,
  "Error": {
    "Code": "INTERNAL_ERROR",
    "Message": "Failed to complete booking with supplier: Activity no longer available"
  }
}

Possible causes:

Activity sold out between cart and payment

Flight no longer available

Supplier system temporarily down

TIP

Recovery Strategy

When supplier booking fails on status transition to paid:

Alert customer immediately about the issue

Offer to find alternative options (different date, similar activity)

Process refund if customer doesn't want alternatives

Log the failure for analysis

Item Status vs Booking Status

Bookings have a top-level status, and each item within the booking also has its own status:

Booking Status: paid (payment confirmed)
Item Statuses: Individual tracking per supplier

Item 1 (Activity): booked - Successfully confirmed with Musement

Item 2 (Transfer): booked - Successfully confirmed with Exfinity

Item 3 (Package): paid - Pending confirmation from Peakwork

When all items reach booked status, you can transition the booking to booked status overall.

Next Steps

Now that you understand bookings:

Review the Booking API Endpoints - Detailed endpoint documentation

Explore Payment Integration - How to process payments before setting status to paid

Learn About Webhooks - Get notified of booking status changes

See Error Handling Guide - Handle edge cases gracefully

What is a Booking?#

The Shopping Cart Pattern#

Open Bookings as Shopping Carts#

Building a Trip#

Booking Lifecycle and Statuses#

Status Overview#

Status Transitions#

Critical Status: paid#

Common Booking Workflows#

Workflow 1: Complete Booking Flow#

Workflow 2: Retrieve Booking History#

Workflow 3: Retrieve Single Booking#

Which Endpoint to Use?#

getOpenBooking#

saveOpenBooking#

saveBookingStatus#

listBookings#

getBooking#

Best Practices#

Error Handling#

Common Scenarios#

Item Status vs Booking Status#

Next Steps#

What is a Booking?

The Shopping Cart Pattern

Open Bookings as Shopping Carts

Building a Trip

Booking Lifecycle and Statuses

Status Overview

Status Transitions

Critical Status: `paid`

Common Booking Workflows

Workflow 1: Complete Booking Flow

Workflow 2: Retrieve Booking History

Workflow 3: Retrieve Single Booking

Which Endpoint to Use?

`getOpenBooking`

`saveOpenBooking`

`saveBookingStatus`

`listBookings`

`getBooking`

Best Practices

Error Handling

Common Scenarios

Item Status vs Booking Status

Next Steps