Frequently asked questions about the Opportunities API

This FAQ answers some common questions related to the Opportunities API.

What is the Opportunities API?

The Opportunities API enables you to discover business opportunities for your connected properties. These opportunities aim to improve the property's chances of gaining more bookings. Each opportunity details what it is about and what actions you and the property can take.

In the Extranet, properties can find the actions specific for them in the Opportunity Center. Properties can add products and deals that help increase bookings and revenue. Some also improve the guests' experiences. The Opportunities API replicates the Opportunity Center in the properties' Extranets. It enables you to show opportunities to the properties.

You can also find an overview of all the opportunities that apply to your properties on the Provider Portal.

To retrieve opportunities a property is eligible for via the API, you can send requests via the GET /opportunity-api/opportunities endpoint. Opportunities are dynamic and not eligible for all properties. The eligibility depends on the settings and performance of the property.

To start using the Opportunities API, you can first retrieve all opportunities for a property via the GET /opportunity-api/properties/{property_id}/opportunities request. The endpoint returns the following information:

Lists all the available opportunities that the property can implement
Lists the reasons why the property should implement the open opportunities
Describes the available actions and how to implement any of the open opportunities

What are date-level inventory opportunities?

Our system generates these opportunities for specific dates whenever it detects inventory situations. As these opportunities are inventory-related, they’re also classified as Provider opportunities. This means that the property must implement them on your platform (or by their PMS), not via our Extranet.

These opportunities differ from other Booking.com opportunities because they’re:

recurring
generated at room- and date-level, and not at the property level
time-sensitive (eligibility can change from one day to the next)

Date-level inventory opportunities highlight the following:

specific dates with no inventory (such as high-demand dates)
blocked inventory (inventory not shown to guests because of potential incorrect restrictions)

How do I access date-level inventory opportunities?

You can access date-level inventory opportunities by implementing the date_level_inventory_opportunities feature. The feature enables you to access opportunities for specific room and date combinations. You can find these opportunities in the implementation_data element, with stay_id as the entity_type and roomid_staydate which specify the room ID and the date), such as the high_demand_dates_inventory opportunities.

You can then retrieve date-level inventory opportunities such as high_demand_dates_inventory opportunities by using the query parameter opportunity_id.

How do I activate the `date_level_inventory_opportunities` feature?

Once you’ve implemented the Opportunities API, you can enable the date_level_inventory_opportunities feature by taking the following steps:

Log in to connect.booking.com.
Click on the Administration tab.
Select Feature Management from the drop-down menu.
Scroll down the list and find the feature named Date-level inventory opportunities. To view an example in the API response, click on the feature name or View Details.
Use the toggle to enable the feature, and then click on the Save button.

Once you've enabled the feature, you can start retrieving date-level inventory opportunities by calling the GET /opportunity-api/opportunities?opportunity_id={opportunity_id} endpoint.

What's the best way to implement date-level inventory opportunities?

Every property management platform has its own unique characteristics and constraints. That’s why there aren’t any specific rules for integrating date-level inventory opportunities. However, we do have suggestions for when, where and how you should display these opportunities to your properties.

The following sections list few best practices when implementing date-level inventory opportunities in your system.

When should I query date-level inventory opportunities?

You can query them every three hours. You can also query them every time a property logs in to your system or accesses the page where you display opportunities.

Where should I display date-level inventory opportunities?

You can display them on pages that properties use to manage their inventory or restrictions. Those pages could be the calendar, inventory overview, dashboard or any other primary entry page.

Alternatively, you can consider adding these opportunities on any existing notification or opportunity center in your platform. Make sure you highlight them on top of the list, and that the click-through redirects them to the relevant pages. Make sure to always highlight the specific dates, so it’s easier for your properties to take action.

How should I visualize date-level inventory opportunities?

We don’t have specific rules for integration. However, we recommend highlighting them as urgent and adding a clear call to action, such as “Update availability” or “Ease restrictions”. You can visualize multiple stay dates for a date-level inventory opportunity in an accordion fashion, vertically stacked together under one opportunity card.

How should I notify properties about date-level inventory opportunities?

We recommend taking one of the following approaches:

using a notification or opportunity center in your channel manager
displaying them as actionable modals or pop-ups in your dashboard or on your calendar page

In both cases, we advise visually distinguishing these opportunities from other notifications. This will help properties find and take action on them.

How will properties act on date-level inventory opportunities?

Properties should act on these opportunities on their primary interface for inventory management. That gives us two scenarios:

Using the channel manager as the primary system for managing inventory

Properties will take action on the channel manager platform. In this case, clicking on the opportunity notification should redirect users to their inventory management page (for High Demand Dates opportunities).

Using the channel manager as the secondary system

The property uses the property management system to manage the inventory and synchronizes with the channel manager. In such a case, you can place a separate message on the channel manager platforms to inform users of where they should take action. You can show messages such as “Please go to PMS and add availability”, or “Please ease restrictions from your PMS”.

In both scenarios, properties should add inventory via the Rates & Availability API.

How can I mark opportunities that were implemented?

Our system automatically tracks implemented opportunities. Thus, you do not need to send confirmation to us after you’ve actioned on an opportunity.

How can I use test data to validate the high-demand dates feature?

We want to help you test if the High-Demand Dates feature is working for you and if you’ve optimized your workflow for it. High-Demand Dates are read-only provider-type opportunities. It is challenging to support end-to-end testing because the implementation stays on your platform.

However, you can request simulated opportunities to help validate your implementation. You can then use this testing data to develop this feature for your platform. This will ensure your properties are ready to action when opportunities appear.

How do I access high-demand dates test data?

High-demand dates opportunities appear when a room that would have been bookable on a specific high-demand date is not available.

You can request high-demand date opportunities for test properties if you meet the following requirements:

You've successfully implemented the Opportunities API
You've enabled the high_demand_dates_inventory feature via the Provider Portal
You've at least one test hotel set up in our system with rooms, rate plans and inventory properly mapped
You've sent a request via the GET /opportunity-api/opportunities?opportunity_id={opportunity_id} endpoint for high_demand_dates_inventoryand identified the three predetermined high-demand dates (i.e. next Saturday, next Sunday or 21 days from the time of each request)
You've created a "dummy" high demand dates by reserving all the available rooms for a bookable room type for one of the three predetermined high-demand dates so it is sold-out

Notes:

Outside of the testing environment, there are no predetermined high-demand dates, and the eligibility is dynamic. We recommend checking for these opportunities for your properties once every three hours or more.
Please do not use live data for testing.

What can I do with high-demand dates test data?

You can use these test data to validate the following use cases of the High-Demand Dates feature.

Use Case 1:

Retrieve a list of all eligible high_demand_date_inventory opportunities for a specific property. Use this to validate your implementation of the core user journey.

Here’s how to do it:

Set up a test property in our system with rooms, rate plans and inventory mapped. Create a "dummy" high demand dates by reserving all the rooms for a bookable room type for one of the three predetermined high-demand dates
Fetch all opportunities for a test property by using the GET /opportunity-api/properties/{property_id}/opportunities endpoint
Parse the API response for high_demand_dates_inventory opportunity_id
Parse the implementation data of high_demand_dates_inventory opportunity_id for all stay_ids
Split the value of stay_ids to retrieve room_ids and stay_dates
Test the implementation flow of any eligible opportunities

Optional step

Reset availability to zero for the same stay dates to make these opportunities available again for further testing.

Recommended steps

Test the following scenarios:

implementing for a single room on a single date
implementing for multiple rooms on a single date
handling zero eligible opportunities
implementing for multiple rooms on multiple dates

Use Case 2:

Fetch a list of all properties currently eligible for high demand dates inventory opportunities. You can use the output to get a view of currently eligible properties. We recommend fetching at least every three hours.