Paid ancillaries for hotel booking

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Travelers can purchase ancillaries (or add-ons) along with their hotel booking. Common ancillaries include early check-in, late checkout, Wi-Fi access, breakfast, and parking. Spotnana APIs allow you to fetch the available ancillaries for an available rate, include them when creating a new booking, or modify them as part of an existing reservation.

Paid ancillary categories

Each ancillary returned by the API belongs to an ancillary category (listed below). The category field indicates the type of service offered and is useful when deciding how to group or display them in your user interface.

Fetching available ancillaries

Use the get hotel ancillaries API to retrieve the list of paid ancillaries available for a selected hotel rate. The request takes the priceValidateKey returned from step 2 of the creating a hotel booking workflow.

Here's a sample request body of the get hotel ancillaries API:

{
  "priceValidateKey": "Cg5TUE9UTkFOQTozMDc3NhIgCgIIARIMCgoyMDI0LTA="
}

The response contains an ancillaries array, where each item describes an ancillary available to purchase for the selected room. The totalRate object holds the price information for each ancillary. The key fields are:

Here's a sample response from the get hotel ancillaries API containing two available ancillaries:

{
  "ancillaries": [
    {
      "ancillaryKey": "EICHK001",
      "category": "EARLY_CHECKIN",
      "displayName": "Early check-in from 12pm",
      "description": "Check in from 12 noon to 2:30pm instead of the standard 3pm. Subject to availability.",
      "totalRate": {
        "base":  { "amount": 15.00, "currencyCode": "GBP" },
        "tax":   { "amount":  0.00, "currencyCode": "GBP" },
        "total": { "amount": 15.00, "currencyCode": "GBP" }
      },
      "prepaidRate": {
        "base":  { "amount": 15.00, "currencyCode": "GBP" },
        "tax":   { "amount":  0.00, "currencyCode": "GBP" },
        "total": { "amount": 15.00, "currencyCode": "GBP" }
      },
      "refundability": "FULLY_REFUNDABLE",
      "purchaseStatus": "AVAILABLE",
      "paymentType": "PREPAID"
    },
    {
      "ancillaryKey": "BFAST002",
      "category": "BREAKFAST",
      "displayName": "Full English Breakfast",
      "description": "Cooked-to-order breakfast included for every night of the stay.",
      "totalRate": {
        "base":  { "amount": 19.00, "currencyCode": "GBP" },
        "tax":   { "amount":  0.00, "currencyCode": "GBP" },
        "total": { "amount": 19.00, "currencyCode": "GBP" }
      },
      "prepaidRate": {
        "base":  { "amount": 19.00, "currencyCode": "GBP" },
        "tax":   { "amount":  0.00, "currencyCode": "GBP" },
        "total": { "amount": 19.00, "currencyCode": "GBP" }
      },
      "refundability": "FULLY_REFUNDABLE",
      "purchaseStatus": "AVAILABLE",
      "paymentType": "PREPAID"
    }
  ]
}

Understanding purchaseStatus and status

Each ancillary returned by the get hotel ancillaries API carries two distinct state fields: purchaseStatus and status. These two fields work together. Collectively, they can be used to understand the overall status of the ancillary before and after purchase.

The following are some possible combinations you can expect:

Booking a hotel with ancillaries

To include ancillaries in a new hotel booking, pass the ancillaryKeys array in the request when creating a new hotel PNR.

{
  "bookingKey": "example_booking_key",
  "travelers": [
    // ... traveler details
  ],
  "tripData": {
    "tripId": { "id": "2783425534" }
  },
  "ancillaryKeys": [
    "EICHK001",
    "BFAST002"
  ]
}

Once a new booking is created, you can use the get PNR API to review the rate of the purchased ancillary in the following places:

1. The hotelPnr > ancillaries > totalRate field. Each ancillary uses a dedicated hotelPnr > ancillaries > totalRate > roomFees > feeType field. This makes it easy to distinguish ancillary charges from other charges (e.g., taxes) when displaying the price breakdown (e.g., feeType can contain HOTEL_ANCILLARY_EARLY_CHECK_IN_FEE which indicates the price of the early check-in fee).
2. The hotelPnr > room > rateInfo > totalRate > extras > amount field. Use the extras > type field to find the ancillary category (e.g., type = HOTEL_ANCILLARY_EARLY_CHECK_IN_FEE).
3. The hotelPnr > room > rateInfo > prepaidRate > extras > amount field if the purchase is prepaid.
4. The hotelPnr > room > rateInfo > postpaidRate > extras > amount field if the purchase is postpaid and will be charged when checking into the property.

Modifying ancillaries on an existing booking - Overview

Ancillaries can be added, removed, or modified as part of an existing hotel booking. For the full step-by-step API sequence to do this, see the modifying ancillaries in a hotel booking workflow.

The key behavior to understand is that the modify hotel booking endpoint reconciles ancillaries using a delete-and-add pattern. The ancillaryKeys array in the request body represents the complete state of the booking's ancillaries after the modification is applied, not a list of changes to make.

Sample use case

A traveler has an existing booking with early check-in (ancillaryKey = EICHK001) and breakfast (ancillaryKey = BFAST002) already purchased. They want to cancel the early check-in, keep the breakfast, and add a Wi-Fi package (ancillaryKey = WIFI007). The intended final state of the ancillaryKeys array will be breakfast and Wi-Fi as shown below in the sample API request:

{
  "bookingKey": "example_booking_key",
  "travelers": [
    // ... traveler details
  ],
  "tripData": {
    "tripId": { "id": "2783425534" }
  },
  "ancillaryKeys": [
    "BFAST002",
    "WIFI007"
  ]
}

This API call will cancel the early check-in ancillary (issuing a refund if applicable) and will add the new Wi-Fi package service to the booking. The booking also retains the breakfast service which was originally purchased. The final cost the traveler has to pay for this modification will be reflected in the totalRate > roomFees.

Cancellation and refunds

Ancillaries can be canceled using the modifying ancillaries workflow. Also, the purchased ancillaries will be canceled automatically if the hotel booking is canceled. The refund process for each ancillary is treated according to its refundability value:

• Applicable refunds are processed for ancillaries if refundability is set to FULLY_REFUNDABLE or PARTIALLY_REFUNDABLE.
• Ancillaries with refundability set to NON_REFUNDABLE are not refunded.