POST /travel/book — Initiate and Retrieve Bookings

This page covers two closely related endpoints: creating a new booking from a search offer, and retrieving the current status of an existing booking. Use POST /travel/book to convert an offerId from /travel/search into a confirmed reservation, and GET /travel/booking/{id} to check on that booking at any point afterward. Both endpoints are available to Enterprise and Developer partners.

Base URLs

International: https://api.rollinggo.ai/v1
China: https://api.rollinggo.cn/v1

Authentication

Include your API key as a Bearer token in the Authorization header on all requests:

Authorization: Bearer rg_live_xxxxxxxxxxxxxxxxxxxx

Create a Booking

POST https://api.rollinggo.ai/v1/travel/book

Submit an offerId from /travel/search along with passenger details and contact information to create a booking. On success, you receive a bookingId and PNR that you can use to retrieve or reference the booking later.

Request Parameters

string

required

The offer identifier returned by POST /travel/search. This value expires 15 minutes after the search — if it has expired, call /travel/search again to obtain a fresh one.

array

required

A list of passenger objects. The number of passengers must match the passengers count used in the original search.

Show Passenger object fields

string

required

Passenger’s given name, exactly as it appears on their travel document.

string

required

Passenger’s family name, exactly as it appears on their travel document.

string

required

Passenger’s date of birth in YYYY-MM-DD format.

string

required

Type of identity document. Accepted values are passport and national_id.

string

required

The document’s identification number.

string

required

Document expiry date in YYYY-MM-DD format. The document must be valid for the duration of travel.

string

required

Email address where the booking confirmation is sent.

string

required

Passenger contact phone number including country code (e.g., +85291234567).

Example Request

{
  "offerId": "offer_cx520_20250901",
  "passengers": [
    {
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "1990-05-15",
      "documentType": "passport",
      "documentNumber": "A12345678",
      "documentExpiry": "2030-01-01"
    }
  ],
  "contactEmail": "jane.doe@example.com",
  "contactPhone": "+85291234567"
}

Example Response

{
  "status": "ok",
  "requestId": "req_9ab3cx",
  "bookingId": "bk_XYZ9012",
  "bookingStatus": "confirmed",
  "pnr": "RGX7AB",
  "totalPrice": {
    "amount": 3200,
    "currency": "HKD"
  },
  "confirmationEmail": "jane.doe@example.com"
}

Response Fields

string

"ok" on a successful response.

string

A unique identifier for this request. Include this when contacting support.

string

A unique identifier for the created booking. Save this — you use it to retrieve the booking with GET /travel/booking/{id}.

string

The current state of the booking. See Booking Status Values below.

string

The airline-issued Passenger Name Record (PNR) locator code (e.g., RGX7AB). Passengers use this code to check in and manage their reservation directly with the carrier.

object

The total charged amount for the booking.

Show totalPrice fields

number

The total fare amount.

string

The ISO 4217 currency code for the amount.

Retrieve a Booking

GET https://api.rollinggo.ai/v1/travel/booking/{id}

Retrieve the current status and full details of an existing booking using its bookingId. The response shape mirrors the booking creation response, reflecting the latest bookingStatus.

Path Parameters

string

required

The bookingId returned by POST /travel/book (e.g., bk_XYZ9012).

Example Request

GET https://api.rollinggo.ai/v1/travel/booking/bk_XYZ9012
Authorization: Bearer rg_live_xxxxxxxxxxxxxxxxxxxx

Example Response

The response has the same shape as the booking creation response, with the most up-to-date bookingStatus:

{
  "status": "ok",
  "requestId": "req_4mn1pq",
  "bookingId": "bk_XYZ9012",
  "bookingStatus": "confirmed",
  "pnr": "RGX7AB",
  "totalPrice": {
    "amount": 3200,
    "currency": "HKD"
  },
  "confirmationEmail": "jane.doe@example.com"
}

Booking Status Values

Status	Meaning
`confirmed`	The booking is active and the reservation is held with the carrier.
`pending`	The booking is being processed. Poll again in a few seconds.
`failed`	The booking could not be completed. No charge was made.
`cancelled`	The booking was successfully cancelled.

Error Responses

Offer IDs expire 15 minutes after the original search. If you receive an expired_offer error, call POST /travel/search again to get a fresh offerId and re-submit your booking request.

HTTP Status	Code	Description
400	`invalid_params`	A required field is missing or a value is in an invalid format.
401	`unauthorized`	The API key is missing, invalid, or revoked.
404	`not_found`	The `bookingId` does not exist or does not belong to your account.
422	`expired_offer`	The `offerId` has expired — call `/travel/search` again to get a new one.
422	`unavailable`	The offer is no longer available at the quoted price. Search again for current options.

Overview

MCP Endpoints

POST /travel/book — Initiate and Retrieve Bookings

Authentication

Create a Booking

Request Parameters

Example Request

Example Response

Response Fields

Retrieve a Booking

Path Parameters

Example Request

Example Response

Booking Status Values

Error Responses

​Authentication

​Create a Booking

​Request Parameters

​Example Request

​Example Response

​Response Fields

​Retrieve a Booking

​Path Parameters

​Example Request

​Example Response

​Booking Status Values

​Error Responses

Authentication

Create a Booking

Request Parameters

Example Request

Example Response

Response Fields

Retrieve a Booking

Path Parameters

Example Request

Example Response

Booking Status Values

Error Responses