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 checks offer → Calls checkOffer to confirm live availability and get the current price

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

`checkOffer`

Use when: Verifying live availability and refreshing price before booking

✅ Customer selects a package offer from search results

✅ Displaying offer details or adding to cart

✅ Pre-checkout confirmation of price and availability

✅ Batch-checking multiple offers the customer is comparing

Key behavior: Returns AVAILABLE, NOT_AVAILABLE, or UNKNOWN per offer with refreshed price. Accepts up to 10 offers per request, checked in parallel.

`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

Checking Offer Availability

Package offers returned by sendMessage can become stale -- prices shift and rooms sell out between search and checkout. checkOffer performs a real-time availability and price check against the supplier so your UI always shows current data.

When to Call It

Call checkOffer when a customer selects an offer, adds it to their cart, or reaches a checkout page. Avoid calling it on every search result -- reserve it for offers the customer has expressed interest in.

Position in the flow:

Search -- Customer searches for packages via sendMessage and browses results

Check -- Customer selects an offer; your app calls checkOffer to get the current price and confirm availability

Book -- If the offer is AVAILABLE, proceed to create the booking with the refreshed price

Request Structure

Send up to 10 offers per request. Each item requires:

OfferKey -- A client-defined identifier (printable ASCII, max 256 characters). Echoed back so you can match results to your UI elements.

GiataID -- The hotel identifier from Products[].ProviderID in the sendMessage response (cast the string to an integer). This value lives on the product, not inside the PackageOffer object.

PackageOffer -- A single offer from Products[].Details.PackageOffers[] in the sendMessage response. Pass it through unchanged.

TravellerAges (optional) -- Array of traveller ages (up to 9, each between 0 and 120). Defaults to a single adult aged 30 if omitted.

The top-level Locale field controls the language of returned messages (e.g. "de", "en").

Required sub-fields inside PackageOffer:

Accommodation.ArrivalDate -- Arrival date in YYYY-MM-DD format

Accommodation.LengthOfStay -- Number of nights (must be greater than 0)

Accommodation.Rooms[0].BookingCode -- The room booking code (e.g. "DB1U")

The return date is computed server-side from the arrival date and length of stay -- you do not need to send it. If Price.Currency is set inside PackageOffer, it is used as the preferred currency for the price check; otherwise the system defaults to EUR.

Result Statuses

Status	Meaning	Client Action
`AVAILABLE`	Offer is sellable at the returned price	Display refreshed `Price` / `Currency` and allow booking
`NOT_AVAILABLE`	Offer exists but cannot be sold	Show the user that this offer is no longer available. Check `Reason` for details (e.g. `"accommodation"`, `"transport"`, `"accommodation,transport"`)
`UNKNOWN`	No match found, upstream error, or timeout	Treat as unavailable. Check `Error` for diagnostic details

When an offer comes back as AVAILABLE, always use the refreshed Price and Currency instead of the original search price.

Example

Response:

{
  "Results": [
    {
      "OfferKey": "cart-item-1",
      "Status": "AVAILABLE",
      "SubStatus": "",
      "Price": 1299.50,
      "Currency": "EUR",
      "Reason": "",
      "Error": ""
    }
  ]
}

Limits

Batch size: 1 to 10 offers per request. Exceeding 10 returns a 400 error.

Parallelism: All offers in a request are checked in parallel -- one slow or failing check does not block the others.

Timeout: 60 seconds per request.

TIP

Checking more than 10 offers

Split them into batches of 10 and send the requests concurrently. Each batch is processed independently.

Availability checking must be enabled on your project. If it is not enabled, checkOffer returns a 400 error. Contact your account manager to enable this feature.

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

Offer No Longer Available (from saveOpenBooking?checkBeforePayment=true or checkBookingAvailability):

{
  "Data": null,
  "Error": {
    "Code": "BAD_REQUEST",
    "Message": "offer is no longer available: accommodation"
  }
}

The message includes a reason suffix indicating which component is unavailable:

accommodation -- the hotel is no longer available

transport -- the flight is no longer available

accommodation,transport -- both hotel and flight are unavailable

unknown -- the unavailable component could not be determined

Possible causes:

Hotel room sold out since the offer was originally retrieved

Flight no longer available or sold out

Both components became unavailable

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#

checkOffer#

getBooking#

Checking Offer Availability#

When to Call It#

Request Structure#

Result Statuses#

Example#

Limits#

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`

`checkOffer`

`getBooking`

Checking Offer Availability

When to Call It

Request Structure

Result Statuses

Example

Limits

Best Practices

Error Handling

Common Scenarios

Item Status vs Booking Status

Next Steps