Cancellation details

Overview

The BHI B2B API provides cancellation policy information similar to the PPN API representation, but with a different field structure. You can use the following information to map your implementation to the new policy data structure.

Display cancellation details at search

"CANCELLATION_DETAIL" request field in the BHI B2B API:
- In the PPN API, you receive the cancellation details in the search response by default. But in the BHI B2B API, you need to pass the "CANCELLATION_DETAIL" value in the features.extra field of the Search API request to receive cancellation policy information in the search response.

Important field mapping - PPN to BHI B2B API

The following table shows the BHI B2B API fields that you can use to derive the equivalent cancellation data mapped to the PPN API.
- Referenced PPN API: Express.Results/ Express.MultiContract/ Express.Contract APIs (See API documentation)
- Mapped BHI B2B API: Refer to the Search 2.0 API Guide to learn more about the related BHI B2B API fields.

📘
Note that the Precheck in BHI B2B API, which has the equivalent purpose of the Express.Contract API, does not return a response body for a successful request. You may display the cancellation details on the checkout page using the Search API data.

PPN API Field	BHI B2B API Field	Description
`cancellation_details` array	`offer.policies.cancellation` object	Parent field which nests cancellation information.
`cancellation_details.description`	`cancellation.description`	Human-readable cancellation policy text.
`date_before`, `date_after`,`penalty_nights` under each policy array item	`segments` array > `dateTime`, `type`, `rates`	- PPN API represents a policy with a cancellation window (`date_before`, `date_after`) and appicable penalty (`penalty_nights`). - In BHI B2B API, you may use the `segments` array which provides the the penalty charge rates for a specific date segment. See the Cancellation details - TBD Guide to learn more.
`refund_type`	`cancellation.freeCancellation`	This is not a one-to-one match of data. You can use the BHI API's `freeCancellation.isAllowed` flag and the `freeCancellation.beforeDateTime` to display a "Free cancellation before <date/time>" label on the listing.

BHI B2B Search 2.0 API response example with cancellation details:

"policies": {
  "cancellation": {
    "freeCancellation": {
      "isAllowed": true,
      "beforeDateTime": "2027-01-03T00:00:00.000-07:00"
    },
    "code": "2D1N_1N",
    "description": {
      "en-us": "Stay flexible! Cancel for free before 2027-01-04 Any cancellation received within 2 days prior to the arrival date will incur the first night's charge. Failure to arrive at your hotel or property will be treated as a No-Show and will incur the first night's charge (Hotel policy)."
    },
    "parameter": [
      {
        "days": 3,
        "charge": "NIGHT",
        "value": 0.0
      },
      {
        "days": 2,
        "charge": "NIGHT",
        "value": 1.0
      },
      {
        "days": 0,
        "charge": "NIGHT",
        "value": 1.0
      }
    ],
    "segments": [
      {
        "dateTime": "2027-01-03T00:00:00.000-07:00",
        "type": "BEFORE",
        "rates": [
          {
            "currency": "USD",
            "price": {
              "inclusiveAmount": 0.00,
              "exclusiveAmount": 0.00,
              "tax": {
                "amount": 0.00
              },
              "fees": {
                "amount": 0.00
              }
            }
          }
        ]
      },
      {
        "dateTime": "2027-01-05T00:00:00.000-07:00",
        "type": "BEFORE",
        "rates": [
          {
            "currency": "USD",
            "price": {
              "inclusiveAmount": 228.53,
              "exclusiveAmount": 201.56,
              "tax": {
                "amount": 23.73
              },
              "fees": {
                "amount": 3.24
              }
            }
          }
        ]
      },
      {
        "dateTime": "2027-01-05T00:00:00.000-07:00",
        "type": "ONWARD",
        "rates": [
          {
            "currency": "USD",
            "price": {
              "inclusiveAmount": 228.53,
              "exclusiveAmount": 201.56,
              "tax": {
                "amount": 23.73
              },
              "fees": {
                "amount": 3.24
              }
            }
          }
        ]
      }
    ]
  }
},

Display cancellation policy in lookup

The following table shows the BHI B2B API fields that you can use to derive the equivalent cancellation data mapped to the PPN API.
- Referenced PPN API: Express.Book/ Express.LookUp APIs (See API documentation
- Mapped BHI B2B API: Refer to the Booking Detail API Guide to learn more about the related BHI B2B API fields.

📘
Note that the Book API in BHI B2B, which is the equivalent of the Express.Book API, only returns the itinerary ID for a successful booking request. You may use the Booking Details API to display the itinerary details post-book.

PPN API Field	BHI B2B API Field	Description
`cancellation_details.description`	`cancellationPolicy`	Human-readable cancellation policy text to display on booking lookup page.
`itinerary.status`	`bookings.status`	Before cancelling, confirm that the booking status is active. See more details about the booking statuses on the Retrieve Bookings Guide.

BHI B2B API Response Sample - Booking Details API

{
	"cancellationPolicy": "Stay flexible! Cancel for free before August 25, 2026. Any cancellation received within 7 days prior to the arrival date will incur the first night's charge. Any cancellation received within 3 days prior to the arrival date will be charged for the entire stay. Failure to arrive at your hotel or property will be treated as a No-Show and will incur a charge of 100% of the booking value (Hotel policy).",
}

Cancellation penalties, refund amount, and cancel request

When a customer wants to cancel a booking, you need to communicate the applicable refund amount and active cancellation policy before submitting the cancellation request.

In the BHI B2B API, this is performed in the following two steps.

Preview cancellation: This is similar to performing the Express.LookUp and displaying the active cancellation policy and applicable refund amount in the PPN API. In the BHI B2B API, this is performed via the Cancel API - Preview request.
Confirm cancellation: When a customer acknowledges the refund amount, you may send the cancel request. This is similar to the Express.Cancel request in the PPN API. In the BHI B2B API, this is performed via the Cancel API - Confirm request.

Important field mapping - PPN to BHI B2B

The following table shows the BHI B2B API fields that you can use to derive the equivalent cancellation data mapped to the PPN API.
- Referenced PPN API: Express.LookUp/Express.Cancel APIs (See API documentation
- Mapped BHI B2B API: Refer to the Cancel API Guide to learn more about the related BHI B2B API fields.

PPN API Field	BHI B2B API Field	Description
`cancellation_details.description`	`cancellationSummary.cancellationPolicy`	This array provides the policy text items to display in the cancellation preview page.
`cancellation_details.source_total_charges`	`cancellationSummary.paymentRate`	The booking total paid.
`cancellation_details.source_refund`	`cancellationSummary.refundRate`	The `refundRate` provides the `inclusive` amount and the respective `currency` to be refunded when the booking is cancelled.

BHI B2B API Response Sample - Cancel API: Preview Cancellation

{
    "cancellationSummary": {
        "bookingId": 2023068251,
        "reference": 989888928,
        "cancellationPolicy": [
            {
                "language": "en-us",
                "policyText": "Stay flexible! Cancel for free before August 25, 2026."
            },
            {
                "language": "en-us",
                "policyText": "Any cancellation received within 7 days prior to the arrival date will incur the first night's charge."
            },
            {
                "language": "en-us",
                "policyText": "Any cancellation received within 3 days prior to the arrival date will be charged for the entire stay."
            },
            {
                "language": "en-us",
                "policyText": "Failure to arrive at your hotel or property will be treated as a No-Show and will incur a charge of 100% of the booking value (Hotel policy)."
            }
        ],
        "paymentRate": [
            {
                "currency": "USD",
                "inclusive": 1102.90
            }
        ],
        "refundRate": [
            {
                "currency": "USD",
                "inclusive": 1102.90
            }
        ]
    }
}

BHI B2B API Response Sample - Cancel API: Confirm Cancellation
- A successful cancellation will return a success state with no response.
- You may perform a lookup using the Booking Details API and confirm that the booking status is updated to reflect the cancellation.

📘
Before cancelling, check isFeeWaiverAllowed in Booking Detail. If true, a fee waiver request can be submitted to the hotel.