Book_Lodging_Service_BookRequest_v1

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hotel-engine/json-schema/hotel-engine-v1-book-request-schema.json",
  "title": "Book_Lodging_Service_BookRequest_v1",
  "description": "A request to purchase and reserve an [OfferSummary].",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hotel-engine-lodgingbookingservice-api-openapi.yml#/components/schemas/v1BookRequest",
  "type": "object",
  "properties": {
    "continuationToken": {
      "type": "string",
      "description": "An `continuation_token` from [LodgingBookingService.ConfirmOffer]."
    },
    "guests": {
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "#/$defs/v1RoomGuests"
      },
      "description": "The details of the guests staying on the [ReservationDetails].\nThe number of provided RoomGuests entries must match the number of rooms requested during shopping.\nSome Properties may not retain all of the provided guest names and may not honor more than one guest's loyalty per [BookingDetails]."
    },
    "metadata": {
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "#/$defs/v1BookingMetadata"
      },
      "description": "Metadata to be stored and retrieved along with this [BookingDetails]."
    },
    "paymentInfo": {
      "$ref": "#/$defs/v1PaymentInfo",
      "description": "Optionally, the [PaymentInfo] to be used for this booking."
    }
  },
  "$defs": {
    "v1BookingMetadata": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "title": "A textual key to represent the purpose of the metadata, for example, \"Contract ID\".\nKeys must be unique within a [BookingDetails].\nMaximum length: 40 characters",
          "maxLength": 40.0
        },
        "value": {
          "type": "string",
          "title": "A textual value.\nMaximum length: 100 characters",
          "maxLength": 100.0
        },
        "external": {
          "type": "boolean",
          "description": "If true, this Metadata entry will be included on invoices and reports.\nIf false, this entry will only be available via direct API access."
        }
      },
      "description": "Custom Metadata attached to a [BookingDetails].\nMetadata values allow an Omni customer to carry a small amount of context on a [BookingDetails] for their own use.",
      "title": "Book_Lodging_BookingMetadata_v1"
    },
    "v1EngineDirectBill": {
      "type": "object",
      "description": "Indicates payment via Engine Direct Bill.\nIf an Engine Direct Bill account has not been established, an [InvalidPaymentError] error will be returned.",
      "title": "Common_EngineDirectBill_v1"
    },
    "v1Guest": {
      "type": "object",
      "properties": {
        "familyName": {
          "type": "string",
          "description": "The guest's family name or last name."
        },
        "givenName": {
          "type": "string",
          "description": "The guest's given name or first name."
        },
        "isAdult": {
          "type": "boolean",
          "description": "True if the guest is an adult."
        }
      },
      "description": "A traveler for the stay.",
      "title": "Book_Lodging_Guest_v1"
    },
    "v1GuestWithLoyalty": {
      "type": "object",
      "properties": {
        "guest": {
          "$ref": "#/$defs/v1Guest",
          "description": "The traveler details."
        },
        "loyaltyProgramIdentifier": {
          "$ref": "#/$defs/v1LodgingLoyaltyProgramIdentifier",
          "description": "The identifier to provide to the Property during Booking.\nInvalid identifiers may result in Booking failures with some Properties.\nNot all Offers include loyalty rewards."
        }
      },
      "description": "A traveler who may be awarded Loyalty Rewards for the stay.",
      "title": "Book_Lodging_GuestWithLoyalty_v1"
    },
    "v1LodgingLoyaltyProgramIdentifier": {
      "type": "object",
      "properties": {
        "memberId": {
          "type": "string",
          "description": "The identifier provided to the travel by the program administrator."
        }
      },
      "description": "An identifier signifying a traveler's membership in a Loyalty Program.\nLoyalty Program Identifiers are provided by the administrator of that program.\nNot all [OfferSummary] will grant loyalty rewards.",
      "title": "Common_LodgingLoyaltyProgramIdentifier_v1"
    },
    "v1PaymentCard": {
      "type": "object",
      "properties": {
        "number": {
          "type": "string",
          "description": "The payment card number as a string of digits without any separators or whitespace."
        },
        "securityCode": {
          "type": "string",
          "description": "The card security code, such as CVV or CVC."
        },
        "expirationMonth": {
          "type": "string",
          "description": "The number representing the card’s expiration month (01 through 12). Leading zeroes should be included."
        },
        "expirationYear": {
          "type": "string",
          "description": "Four-digit number representing the card’s expiration year."
        },
        "billingAddress": {
          "$ref": "#/$defs/v1PostalAddress",
          "description": "The billing address associated with the payment card being charged."
        }
      },
      "description": "The payment card that will be charged.",
      "title": "Common_PaymentCard_v1"
    },
    "v1PaymentInfo": {
      "type": "object",
      "properties": {
        "engineDirectBill": {
          "$ref": "#/$defs/v1EngineDirectBill"
        },
        "paymentCard": {
          "$ref": "#/$defs/v1PaymentCard"
        }
      },
      "description": "The payment method used in a request.\nIf omitted, the default payment method configured for the caller will be used.\nIf no default payment method is configured, an [InvalidPaymentError] error will be returned.",
      "title": "Common_PaymentInfo_v1"
    },
    "v1PostalAddress": {
      "type": "object",
      "properties": {
        "recipients": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Optionally, any individual recipients.\nFor example, \"Alexander Hamilton\", \"Aaron Burr\"\nMay be empty."
        },
        "organization": {
          "type": "string",
          "description": "Optionally, any organization or company as a recipient.\nFor example, \"Engine\"."
        },
        "addressLine": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Optionally, any address lines, in order as they'd appear on an envelope.\nFor example, \"233 S Wacker Dr\", \"108th Floor\".\nMay be empty."
        },
        "administrativeArea": {
          "type": "string",
          "title": "Optionally, the State, province, prefecture, oblast, or area.\nFor example, \"Texas\""
        },
        "locality": {
          "type": "string",
          "title": "Optionally, the City, or Post Town\nFor example, \"Austin\""
        },
        "postalCode": {
          "type": "string",
          "description": "Optionally, the postal code, if one exists, for the address.\nFor example, \"78757\"."
        },
        "countryCode": {
          "type": "string",
          "title": "Optionally, the ISO 3166-1 alpha-2 country code.\nFor example, \"US\".\nSee https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2\nSee https://www.iso.org/iso-3166-country-codes.html"
        }
      },
      "description": "Represents a Postal Address.",
      "title": "Common_PostalAddress_v1"
    },
    "v1RoomGuests": {
      "type": "object",
      "properties": {
        "primaryGuest": {
          "$ref": "#/$defs/v1GuestWithLoyalty",
          "title": "The primary guest of a room"
        },
        "additionalGuests": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/$defs/v1Guest"
          },
          "description": "Any additional names you wish to be able to check-in to the room without the [RoomGuests.primary_guest] present.\nNot all Properties allow additional guests to check-in.\nThe primary guest should not be included in the `additional_guests` field."
        }
      },
      "description": "Details of the guests staying within a single room during the stay.",
      "title": "Book_Lodging_RoomGuests_v1"
    }
  }
}