{ "openapi": "3.1.0", "info": { "title": "Booking.com Demand API", "version": "3.1", "summary": "The Booking.com Demand API enables Affiliate Partners to access Booking.com's travel inventory, including accommodations, car rentals, and flights. \n\nUse Demand API to search, retrieve details, check availability, manage bookings and run reports using orders details.\n\n- RESTful API with JSON responses.\n- Make HTTPS POST requests to interact with endpoints.\n- Requires authentication using your Affiliate ID and token credentials.\n\n[Check the try out guide!](/demand/docs/getting-started/try-out-the-api)\n" }, "servers": [ { "url": "https://demandapi.booking.com/3.1", "description": "Production environment" }, { "url": "https://demandapi-sandbox.booking.com/3.1", "description": "Sandbox environment" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "string" } }, "parameters": { "AffiliateIdHeader": { "in": "header", "name": "X-Affiliate-Id", "schema": { "type": "integer" }, "required": true, "description": "Include here your Affiliate identifier number" } } }, "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Accommodations", "x-displayName": "Accommodation", "description": "This API collection is specific for the stay part of the connected trip.

Use these endpoints to search for stays such as hotels and apartments, check availability, retrieve reviews, and get detailed property information." }, { "name": "Cars", "x-displayName": "Car rentals", "description": "This API collection is specific to the car rentals part of the connected trip.

Use these endpoints to search for car rentals, check car details and look for depots and suppliers." }, { "name": "Common/locations", "x-displayName": "Locations", "description": "Provides identifiers for a wide range of geographical locations, including airports, countries, cities, and regions.

Use these identifiers to construct your requests.

Note: These identifiers are available across all travel services and you can use them for both accommodotation and car rentals requests." }, { "name": "Common/payments", "x-displayName": "Payments", "description": "Provides generic payment-related endpoints, including supported currencies and payment types." }, { "name": "Common/languages", "x-displayName": "Languages", "description": "Provides a list of supported language codes for use in API requests." }, { "name": "Orders", "x-displayName": "Orders", "description": "Enables management of booking orders within the Demand API.

Use these endpoints to preview and create new orders, check order details, cancel or modify existing orders. This collection is required to integrate booking and order management functionality. " }, { "name": "Messages", "x-displayName": "Messages", "description": "Provides endpoints for two-way post-booking communication between guests and properties.

Use these endpoints to send and retrieve messages, exchange images, and check conversation details." }, { "name": "Conversations", "x-displayName": "Conversations", "description": "Provides endpoints to retrieve and manage messaging conversations.

Use these endpoints to list conversations, fetch conversation details, and track updates." }, { "name": "Attachments", "x-displayName": "Attachments", "description": "Provides endpoints for handling message attachments.

Use these endpoints to upload and download images shared within conversations." } ], "x-tagGroups": [ { "name": "Travel services", "tags": [ "Accommodations", "Cars" ] }, { "name": "Common", "tags": [ "Common/locations", "Common/payments", "Common/languages" ] }, { "name": "Orders", "tags": [ "Orders" ] }, { "name": "Messaging", "tags": [ "Messages", "Conversations", "Attachments" ] } ], "paths": { "/accommodations/search": { "post": { "summary": "Search accommodation", "description": "This endpoint returns, by default, the cheapest available product for each accommodation that matches the specified search criteria.

When you apply location filters using parameters such as country or region id, the results are sorted by Booking.com popularity (top_picks) instead of price.
In this case, accommodations are ranked in descending order of popularity, meaning higher-ranked listings will appear earlier in the response.", "operationId": "/accommodations/search", "parameters": [ { "in": "header", "name": "X-Affiliate-Id", "schema": { "type": "integer" }, "required": true, "description": "Include here your Affiliate identifier number" } ], "tags": [ "Accommodations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "AccommodationsSearchInput", "type": "object", "properties": { "24_hour_reception": { "description": "Filter the result based if the front desk reception is available 24/7. When specified true, the result will filter the products where front desk is available 24/7.", "type": "boolean" }, "accommodation_facilities": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation property facility. Examples of facilities are: Parking, Restaurant, Room service etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 } }, "accommodation_types": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation property type. Examples of accommodation types are: Apartment, Hostel, Hotel etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 } }, "accommodations": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "maxItems": 100 }, "airport": { "description": "A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling common/locations/airports.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "AMS" }, "booker": { "title": "Booker", "description": "The booker's information.", "type": "object", "properties": { "country": { "description": "The booker country for showing the best price for that user and obeying laws regarding the display of taxes and fees.", "type": "string", "pattern": "^[a-z]{2}$" }, "platform": { "description": "The booker platform for showing the platform based deals and prices.", "type": "string", "enum": [ "android", "desktop", "ios", "mobile", "tablet" ] }, "state": { "description": "The booker state for showing the best price for that user and obeying laws regarding the display of taxes and fees. Currently applicable only for country US.", "type": "string", "pattern": "^[a-z]{2}$" }, "travel_purpose": { "description": "The travel purpose of the booker.", "type": "string", "enum": [ "business", "leisure" ] }, "user_groups": { "description": "The user groups that the booker is a member of.", "type": "array", "items": { "type": "string", "enum": [ "authenticated" ] } } }, "required": [ "country", "platform" ] }, "brands": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation brand. Examples of brands are: Radisson Blu, WestCord Hotels, Westin etc. The full list can be obtained by calling /accommodations/chains.", "type": "integer", "minimum": 1 } }, "cancellation_type_filter": { "type": "string", "description": "Filters the results by cancellation type. Supported value: 'free_cancellation'. ⚠ **DEPRECATED**: 'non_refundable' is deprecated and will be removed in further versions.\n", "enum": [ "free_cancellation", "non_refundable" ] }, "checkin": { "description": "The checkin date. Must be within 500 days in the future and in the format yyyy-mm-dd.", "type": "string", "format": "date" }, "checkout": { "description": "The checkout date. Must be later than {checkin}. Must be between 1 and 90 days after {checkin}. Must be within 500 days in the future and in the format yyyy-mm-dd.", "type": "string", "format": "date" }, "city": { "description": "A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.", "type": "integer" }, "coordinates": { "title": "AccommodationsSearchCoordinatesOutput", "description": "Limit the result list to the specified coordinates.", "type": "object", "properties": { "latitude": { "description": "Specify a latitude (as well as a longitude and radius) to do searches around a specific location.", "type": "number", "format": "double" }, "longitude": { "description": "Specify a longitude (as well as a latitude and radius) to do searches around a specific location.", "type": "number", "format": "double" }, "radius": { "description": "The radius is km to search around the specified latitude and longitude.", "type": "number", "format": "double" } } }, "country": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "district": { "description": "A signed integer number that uniquely identifies a district. Typically, districts define known areas within a city. The full list can be obtained by calling common/locations/districts.", "type": "integer", "minimum": 1 }, "dormitories": { "description": "This parameter specifies if the results should include dormitory beds or rooms. The default behaviour will include the dormitory beds or rooms with other results. When this flag is set to 'only', the response will only include dormitory beds or rooms. When this flag is set to 'exclude', the response will exclude dormitory beds or rooms. When this flag is set to 'include', the response will include dormitory beds or rooms with other results.", "type": "string", "default": "include", "enum": [ "include", "exclude", "only" ] }, "extras": { "description": "Input parameter to request for additional information about the products.", "type": "array", "items": { "type": "string", "enum": [ "extra_charges", "products" ] } }, "guests": { "title": "AccommodationsGuests", "description": "The guest details for the request.", "type": "object", "properties": { "allocation": { "description": "The exact allocation of guests to rooms.", "type": "array", "items": { "properties": { "children": { "description": "The children ages for this room.", "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17 } }, "number_of_adults": { "description": "The number of adults for this room.", "type": "integer", "minimum": 1 } }, "required": [ "number_of_adults" ] } }, "children": { "description": "Array with the children ages.", "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17 } }, "number_of_adults": { "description": "The number of adults for the search.", "type": "integer", "minimum": 1 }, "number_of_rooms": { "description": "The number of rooms needed.", "type": "integer", "minimum": 1 } }, "required": [ "number_of_adults", "number_of_rooms" ] }, "landmark": { "description": "A signed integer number that uniquely identifies a relevant geographical landmark, like a monument or a natural attraction. The full list can be obtained by calling common/locations/landmarks.", "type": "integer", "minimum": 1 }, "meal_plan": { "description": "Filter the result based on the selected meal plan. Example: When specified breakfast_included, it will show the product with free breakfast.", "type": "string", "enum": [ "all_inclusive", "breakfast_included", "full_board", "half_board" ] }, "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" }, "payment": { "description": "The payment filter for the request", "type": "object", "properties": { "credit_card_required": { "description": "Filter to show accommodations which require credit card", "type": "boolean" }, "timing": { "description": "This parameter specifies that the results should only return accommodation and blocks that contain the specified payment timings.", "type": "string", "enum": [ "pay_at_the_property", "pay_online" ] } } }, "price": { "description": "If specified, will return only results where the price *per night* falls in the specified range (inclusive). This filter requires that a currency is passed", "type": "object", "properties": { "maximum": { "description": "Set the maximum price per night, in the specified currency, or omit to indicate no upper limit.", "type": "integer" }, "minimum": { "description": "Set the minimum price per night, in the specified currency, or omit to indicate no lower limit.", "type": "integer" } } }, "rating": { "description": "The rating filter for the request", "type": "object", "properties": { "minimum_review_score": { "description": "Show only hotels with review_score >= that. Review score should be in the range 1 to 10.", "type": "integer", "minimum": 0, "maximum": 10 }, "stars": { "description": "Limit to accommodations with the given number(s) of stars. Stars should be in the range of 1 to 5.", "type": "array", "items": { "type": "number", "minimum": 1, "maximum": 5 } } } }, "region": { "description": "A signed integer number that uniquely identifies a geographical region. Regions usually define official administrative areas within a country, but may also include multiple countries and in some cases un-official but popular designations for geographical areas. An example of a region that crosses multiple countries is the Alps in Europe. The full list can be obtained by calling common/locations/regions.", "type": "integer", "minimum": 1 }, "room_facilities": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation property room facility. Examples of facilities are: Coffee/Tea maker, TV, Airconditioning, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 } }, "rows": { "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "maximum": 100, "default": 100 }, "sort": { "description": "The sorting parameters for the response", "type": "object", "properties": { "by": { "description": "The way to sort your results. NOTE: When ordering by distance please make sure to specify the latitude and longitude!", "type": "string", "enum": [ "distance", "price", "review_score", "stars" ] }, "direction": { "description": "The direction you wish for your sort.by parameter to be sorted in", "type": "string", "enum": [ "ascending", "descending" ] } } }, "travel_proud": { "description": "Filter the result based on if the property is LGBTQ+ friendly. When specified true, the result will filter and return only the accommodations that are Proud Certified.", "type": "boolean" } }, "required": [ "booker", "checkin", "checkout", "guests" ] }, "example": { "booker": { "country": "nl", "platform": "desktop" }, "checkin": "!START_DATE!", "checkout": "!END_DATE!", "city": -2140479, "extras": [ "extra_charges", "products" ], "guests": { "number_of_adults": 2, "number_of_rooms": 1 } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "AccommodationsSearchOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "AccommodationsSearchDataOutput", "description": "", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "commission": { "title": "AccommodationsCommission", "description": "Commission details for the partner for a given accommodation", "type": "object", "properties": { "amount": { "description": "The actual commission amount for the partner.", "type": "number", "format": "double", "minimum": 0 }, "percentage": { "description": "Percentage of the fee that will be received as commission.", "type": "number", "format": "double", "minimum": 0 } } }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "deep_link_url": { "description": "A mobile app URL that directs the user to a specific page or content within the Booking.com app. The link can only be used on a device with the Booking.com app installed. It typically includes an Affiliate ID (AID) to attribute bookings to the affiliate partner when users are redirected", "type": "string", "format": "url" }, "price": { "title": "AccommodationsSearchProductPrice", "description": "The price components of this product or selection of products. 'base' and 'extra_charges' are returned only when explicitly requested (via 'extras=extra_charges').", "type": "object", "properties": { "base": { "description": "The base price. It does not include any extra charges.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "book": { "description": "The display price that must be shown to the traveller under local booker protection laws. This price includes the base accommodation cost and all charges that are legally required to be part of the displayed price. Equivalent to base + included charges.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "extra_charges": { "title": "AccommodationsExtraCharges", "description": "The charge breakdown. Includes taxes and fees.", "type": "object", "properties": { "excluded": { "description": "Charges not included in 'book'.", "type": "number", "format": "double", "minimum": 0 }, "included": { "description": "Charges included in 'book'.", "type": "number", "format": "double", "minimum": 0 } } }, "total": { "description": "The total price. Includes all extra charges.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "products": { "type": "array", "items": { "title": "AccommodationsSearchProductOutput", "description": "Details product information. It requires `{\"extras\":[\"products\"]}`.", "type": "object", "properties": { "id": { "description": "Unique ID of the product.", "type": "string" }, "bundle": { "description": "The bundle ID of the product comprising of value added products.", "type": "integer" }, "children": { "description": "The ages of the children allocated to this product.", "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17 } }, "deal": { "title": "Deal", "description": "This specifies the deal tagging for the product.", "type": [ "object", "null" ], "properties": { "discount_percentage": { "description": "Discount percentage of the applied deal.", "type": "integer", "minimum": 1 }, "public_price": { "description": "Original price of this product, before applying any discounts.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "tags": { "description": "The tags of all the applied deals.", "type": "array", "items": { "type": "string", "enum": [ "black_friday", "limited_time_deal", "logged_in_deal", "mobile_rate", "seasonal_deal" ] } } } }, "inventory": { "title": "InventoryOutput", "type": "object", "properties": { "third_party": { "type": "boolean", "description": "Boolean value is \"true\" if the product is facilitated by a Booking.com partner company and \"false\" otherwise." }, "type": { "description": "Type of inventory - either net or sell rates.", "type": "string", "enum": [ "net", "sell" ] } } }, "number_available_at_this_price": { "description": "Number of rooms available at this price.", "type": "integer", "minimum": 1, "nullable": true }, "number_of_adults": { "description": "The number of adults allocated to this product.", "type": "integer", "minimum": 1 }, "policies": { "title": "AccommodationsProductPolicies", "description": "The policies for this product.", "type": "object", "properties": { "cancellation": { "title": "AccommodationsProductCancellationPolicy", "description": "The cancellation policy for this product.", "type": "object", "properties": { "free_cancellation_until": { "description": "Until when the order for this product can be cancelled for free.", "type": [ "string", "null" ], "format": "date-time" }, "type": { "description": "The cancellation policy applicable to this product: \"free_cancellation\" allows a period for free cancellation, \"non_refundable\" means immediate loss of total amount, \"special_conditions\" means partly refundable.", "type": "string", "enum": [ "free_cancellation", "non_refundable", "special_conditions" ] } } }, "meal_plan": { "title": "AccommodationsProductMealPlanPolicy", "description": "The meal plan policy for this product.", "type": "object", "properties": { "meals": { "description": "The meals included in the meal plan.", "type": "array", "items": { "type": "string", "enum": [ "breakfast", "dinner", "lunch" ] } }, "plan": { "description": "The meal plan included in this product.", "type": "string", "enum": [ "all_inclusive", "breakfast_included", "full_board", "half_board", "no_plan" ] } } }, "payment": { "title": "AccommodationsProductPaymentPolicyNew", "description": "Payment terms and conditions for this product.", "type": "object", "properties": { "prepayment_required": { "description": "Whether prepayment is required for this product.", "type": "boolean" }, "timings": { "description": "The payment timings supported by this product.", "type": "array", "items": { "type": "string", "enum": [ "pay_at_the_property", "pay_online_later", "pay_online_now" ] } } } } } }, "price": { "title": "AccommodationsProductPrice", "description": "The price components of this product. 'base' and 'extra_charges' are returned only when explicitly requested (via 'extras=extra_charges').", "type": "object", "properties": { "base": { "description": "The base price. It does not include any extra charges.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "book": { "description": "The display price that must be shown to the traveller under local booker protection laws. This price includes the base accommodation cost and all charges that are legally required to be part of the displayed price. Equivalent to base + included charges.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "extra_charges": { "title": "AccommodationsProductExtraCharges", "description": "The charge breakdown. Includes taxes and fees.", "type": "object", "properties": { "conditional": { "description": "Charges that might apply under a specific condition.", "type": "array", "items": { "title": "AccommodationsConditionalCharge", "description": "Charges that might apply under a specific condition.", "type": "object", "properties": { "charge": { "description": "A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 0 }, "condition": { "description": "A signed integer number that uniquely identifies the condition ID. Find the full list in the Pricing guidelines.", "type": [ "integer", "null" ], "minimum": 0 }, "mode": { "description": "The mode of this charge. Determines how the price is calculated.", "type": "string", "enum": [ "calculated_amount", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay" ] }, "percentage": { "description": "The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "total_amount": { "description": "The total price for this charge.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "unit_amount": { "description": "The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true } } } }, "excluded": { "description": "Charges not included in 'book'.", "type": "array", "items": { "title": "AccommodationsSearchCharge", "description": "All non-conditional charges that will necessarily be paid", "type": "object", "properties": { "charge": { "description": "A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 0 }, "mode": { "description": "The mode of this charge. Determines how the price is calculated.", "type": "string", "enum": [ "calculated_amount", "incalculable", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay" ] }, "percentage": { "description": "The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "total_amount": { "description": "The total price for this charge.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "unit_amount": { "description": "The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true } } } }, "included": { "description": "Charges included in 'book'.", "type": "array", "items": { "title": "AccommodationsSearchCharge", "description": "All non-conditional charges that will necessarily be paid", "type": "object", "properties": { "charge": { "description": "A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 0 }, "mode": { "description": "The mode of this charge. Determines how the price is calculated.", "type": "string", "enum": [ "calculated_amount", "incalculable", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay" ] }, "percentage": { "description": "The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "total_amount": { "description": "The total price for this charge.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "unit_amount": { "description": "The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true } } } } } }, "total": { "description": "The total price. Includes all extra charges.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "room": { "description": "A signed integer number that uniquely identifies an accommodation property room. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "third_party_inventory": { "description": "Boolean value is \"true\" if the product is facilitated by a Booking.com partner company and \"false\" otherwise.", "type": "boolean" } } } }, "url": { "description": "Internet address for the property page on Booking.com.", "type": "string", "format": "url" } } } }, "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`).", "type": [ "string", "null" ] } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 10004, "currency": "EUR", "deep_link_url": "booking://hotel/10004?affiliate_id=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!&mcid=10", "price": { "base": 1081.49, "book": 1260.52, "extra_charges": { "excluded": 0, "included": 179.04 }, "total": 1260.52 }, "products": [ { "id": "1000420_95127794_2_0_0", "bundle": null, "children": [], "deal": null, "inventory": { "third_party": false, "type": "sell" }, "number_of_adults": 2, "policies": { "cancellation": { "free_cancellation_until": null, "type": "non_refundable" }, "meal_plan": { "meals": [], "plan": "no_plan" }, "payment": { "timings": [ "pay_at_the_property" ] } }, "price": { "base": 1081.49, "book": 1260.52, "extra_charges": { "conditional": [], "excluded": [], "included": [ { "charge": 21, "mode": "percentage", "percentage": 9, "total_amount": 107.07, "unit_amount": null }, { "charge": 22, "mode": "percentage", "percentage": 7, "total_amount": 83.27, "unit_amount": null }, { "charge": 142, "mode": "per_person_per_night", "percentage": null, "total_amount": 6, "unit_amount": 3 } ] }, "total": 1260.52 }, "room": 1000426, "third_party_inventory": false } ], "url": "https://www.booking.com/hotel/nl/conscious-the-tire-station.html?affiliate_id=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!&group_adults=2&no_rooms=1" }, "..." ], "next_page": "..." } } } } } } }, "/accommodations/availability": { "post": { "summary": "Check availability", "description": "Use this endpoint to return detailed product availability, price and charges of the accommodation matching a given search criteria.
By default, only product availability and price is returned. To receive extended information use the `extras` parameter.

Note: It is mandatory to pass the input parameters: accommodation, booker, checkin, checkout and guest.", "operationId": "/accommodations/availability", "parameters": [ { "in": "header", "name": "X-Affiliate-Id", "schema": { "type": "integer" }, "required": true, "description": "Include here your Affiliate identifier number" } ], "tags": [ "Accommodations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "AccommodationsAvailabilityInput", "type": "object", "properties": { "accommodation": { "description": "A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "booker": { "title": "Booker", "description": "The booker's information.", "type": "object", "properties": { "country": { "description": "The booker country for showing the best price for that user and obeying laws regarding the display of taxes and fees.", "type": "string", "pattern": "^[a-z]{2}$" }, "platform": { "description": "The booker platform for showing the platform based deals and prices.", "type": "string", "enum": [ "android", "desktop", "ios", "mobile", "tablet" ] }, "state": { "description": "The booker state for showing the best price for that user and obeying laws regarding the display of taxes and fees. Currently applicable only for country US.", "type": "string", "pattern": "^[a-z]{2}$" }, "travel_purpose": { "description": "The travel purpose of the booker.", "type": "string", "enum": [ "business", "leisure" ] }, "user_groups": { "description": "The user groups that the booker is a member of.", "type": "array", "items": { "type": "string", "enum": [ "authenticated" ] } } }, "required": [ "country", "platform" ] }, "checkin": { "description": "The checkin date. Must be within 500 days in the future and in the format yyyy-mm-dd.", "type": "string", "format": "date" }, "checkout": { "description": "The checkout date. Must be later than {checkin}. Must be between 1 and 90 days after {checkin}. Must be within 500 days in the future and in the format yyyy-mm-dd.", "type": "string", "format": "date" }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "extras": { "description": "Input parameter to request for additional information about this product. Add \"include_bundle_variants\" to include all bookable products with bundles.", "type": "array", "items": { "type": "string", "enum": [ "extra_charges", "include_bundle_variants" ] } }, "guests": { "title": "AccommodationsGuests", "description": "The guest details for the request.", "type": "object", "properties": { "allocation": { "description": "The exact allocation of guests to rooms.", "type": "array", "items": { "properties": { "children": { "description": "The children ages for this room.", "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17 } }, "number_of_adults": { "description": "The number of adults for this room.", "type": "integer", "minimum": 1 } }, "required": [ "number_of_adults" ] } }, "children": { "description": "Array with the children ages.", "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17 } }, "number_of_adults": { "description": "The number of adults for the search.", "type": "integer", "minimum": 1 }, "number_of_rooms": { "description": "The number of rooms needed.", "type": "integer", "minimum": 1 } }, "required": [ "number_of_adults", "number_of_rooms" ] }, "payment": { "description": "Payment input information to filter results.", "properties": { "timing": { "description": "This parameter specifies that the results should only return accommodation and blocks that contain the specified payment timings.", "type": "string", "enum": [ "pay_at_the_property", "pay_online" ] } } }, "products": { "type": "array", "items": { "description": "Unique ID of the product.", "type": "string" } } }, "required": [ "accommodation", "booker", "checkin", "checkout", "guests" ] }, "example": { "accommodation": 10004, "booker": { "country": "nl", "platform": "desktop" }, "checkin": "!START_DATE!", "checkout": "!END_DATE!", "extras": [ "extra_charges" ], "guests": { "number_of_adults": 2, "number_of_rooms": 1 } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "AccommodationsAvailabilityOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "title": "AccommodationsAvailabilityDataOutput", "description": "", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "deep_link_url": { "description": "A mobile app URL that directs the user to a specific page or content within the Booking.com app. The link can only be used on a device with the Booking.com app installed. It typically includes an Affiliate ID (AID) to attribute bookings to the affiliate partner when users are redirected", "type": "string", "format": "url" }, "products": { "type": "array", "items": { "title": "AccommodationsAvailabilityProductOutput", "description": "", "type": "object", "properties": { "id": { "description": "Unique ID of the product.", "type": "string" }, "bundle": { "description": "The bundle ID of the product comprising of value added products.", "type": "integer" }, "deal": { "title": "Deal", "description": "This specifies the deal tagging for the product.", "type": [ "object", "null" ], "properties": { "discount_percentage": { "description": "Discount percentage of the applied deal.", "type": "integer", "minimum": 1 }, "public_price": { "description": "Original price of this product, before applying any discounts.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "tags": { "description": "The tags of all the applied deals.", "type": "array", "items": { "type": "string", "enum": [ "black_friday", "limited_time_deal", "logged_in_deal", "mobile_rate", "seasonal_deal" ] } } } }, "inventory": { "title": "InventoryOutput", "type": "object", "properties": { "third_party": { "type": "boolean", "description": "Boolean value is \"true\" if the product is facilitated by a Booking.com partner company and \"false\" otherwise." }, "type": { "description": "Type of inventory - either net or sell rates.", "type": "string", "enum": [ "net", "sell" ] } } }, "maximum_occupancy": { "title": "AccommodationsMaximumOccupancy", "description": "Information related to maximum number of occupancy inside the room.", "type": "object", "properties": { "adults": { "description": "The maximum number of adults for this room.", "type": "integer", "minimum": 1 }, "children": { "description": "The information about maximum number of children and their allowed ages for this room.", "type": "array", "items": { "title": "AccommodationsChildren", "type": "object", "properties": { "total": { "description": "The maximum number of children for this room.", "type": "integer", "minimum": 1 }, "from_age": { "description": "The youngest age of the children allowed in this room.", "type": "integer", "minimum": 0, "maximum": 17 }, "to_age": { "description": "The oldest age of the children allowed in this room.", "type": "integer", "minimum": 0, "maximum": 17 }, "free_stay": { "description": "Whether children in this age bracket will be staying for free. False indicates their cost was already included in the price.", "type": "boolean" } } } }, "total": { "description": "The maximum number of guests for this room.", "type": "integer", "minimum": 1 } } }, "number_available_at_this_price": { "description": "Number of rooms available at this price.", "type": "integer", "minimum": 1 }, "policies": { "title": "AccommodationsProductPolicies", "description": "The policies for this product.", "type": "object", "properties": { "cancellation": { "title": "AccommodationsProductCancellationPolicy", "description": "The cancellation policy for this product.", "type": "object", "properties": { "free_cancellation_until": { "description": "Until when the order for this product can be cancelled for free.", "type": [ "string", "null" ], "format": "date-time" }, "schedule": { "description": "The cancellation policy schedule for this product.", "type": "array", "items": { "title": "AccommodationsProductDetailedCancellationPolicy", "type": "object", "properties": { "from": { "description": "The time from which this cancellation fee applies. `now` means from booking time.", "type": [ "string", "null" ], "oneOf": [ { "format": "date-time" }, { "pattern": "now" } ] }, "price": { "description": "The cancellation fee.", "type": "number", "format": "double", "minimum": 0 } } } }, "type": { "description": "The cancellation policy applicable to this product: \"free_cancellation\" allows a period for free cancellation, \"non_refundable\" means immediate loss of total amount, \"special_conditions\" means partly refundable.", "type": "string", "enum": [ "free_cancellation", "non_refundable", "special_conditions" ] } } }, "meal_plan": { "title": "AccommodationsProductMealPlanPolicy", "description": "The meal plan policy for this product.", "type": "object", "properties": { "meals": { "description": "The meals included in the meal plan.", "type": "array", "items": { "type": "string", "enum": [ "breakfast", "dinner", "lunch" ] } }, "plan": { "description": "The meal plan included in this product.", "type": "string", "enum": [ "all_inclusive", "breakfast_included", "full_board", "half_board", "no_plan" ] } } }, "payment": { "title": "AccommodationsProductPaymentPolicyNew", "description": "Payment terms and conditions for this product.", "type": "object", "properties": { "prepayment_required": { "description": "Whether prepayment is required for this product.", "type": "boolean" }, "timings": { "description": "The payment timings supported by this product.", "type": "array", "items": { "type": "string", "enum": [ "pay_at_the_property", "pay_online_later", "pay_online_now" ] } } } } } }, "price": { "title": "AccommodationsAvailabilityProductPrice", "description": "The price components of this product. 'base' and 'extra_charges' are returned only when explicitly requested (via 'extras=extra_charges').", "type": "object", "properties": { "base": { "description": "The base price. It does not include any extra charges.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "book": { "description": "The display price that must be shown to the traveller under local booker protection laws. This price includes the base accommodation cost and all charges that are legally required to be part of the displayed price. Equivalent to base + included charges.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "chargeable_online": { "description": "The price that will be charged by Booking.com when online payments are used. This field does not apply to the \"pay_at_the_property\" timing.", "nullable": true, "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "extra_charges": { "title": "AccommodationsProductExtraCharges", "description": "The charge breakdown. Includes taxes and fees.", "type": "object", "properties": { "conditional": { "description": "Charges that might apply under a specific condition.", "type": "array", "items": { "title": "AccommodationsConditionalCharge", "description": "Charges that might apply under a specific condition.", "type": "object", "properties": { "charge": { "description": "A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 0 }, "condition": { "description": "A signed integer number that uniquely identifies the condition ID. Find the full list in the Pricing guidelines.", "type": [ "integer", "null" ], "minimum": 0 }, "mode": { "description": "The mode of this charge. Determines how the price is calculated.", "type": "string", "enum": [ "calculated_amount", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay" ] }, "percentage": { "description": "The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "total_amount": { "description": "The total price for this charge.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "unit_amount": { "description": "The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true } } } }, "excluded": { "description": "Charges not included in 'book'.", "type": "array", "items": { "title": "AccommodationsAvailabilityCharge", "description": "All non-conditional charges that will necessarily be paid", "type": "object", "properties": { "charge": { "description": "A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 0 }, "chargeable_online": { "description": "Whether this charge is chargeable online or not. Not applicable to \"pay_at_the_property\" timing.", "type": "boolean", "nullable": true }, "mode": { "description": "The mode of this charge. Determines how the price is calculated.", "type": "string", "enum": [ "calculated_amount", "incalculable", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay" ] }, "percentage": { "description": "The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "total_amount": { "description": "The total price for this charge.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "unit_amount": { "description": "The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true } } } }, "included": { "description": "Charges included in 'book'.", "type": "array", "items": { "title": "AccommodationsAvailabilityCharge", "description": "All non-conditional charges that will necessarily be paid", "type": "object", "properties": { "charge": { "description": "A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 0 }, "chargeable_online": { "description": "Whether this charge is chargeable online or not. Not applicable to \"pay_at_the_property\" timing.", "type": "boolean", "nullable": true }, "mode": { "description": "The mode of this charge. Determines how the price is calculated.", "type": "string", "enum": [ "calculated_amount", "incalculable", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay" ] }, "percentage": { "description": "The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "total_amount": { "description": "The total price for this charge.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "unit_amount": { "description": "The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true } } } } } }, "total": { "description": "The total price. Includes all extra charges.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "room": { "description": "A signed integer number that uniquely identifies an accommodation property room. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "third_party_inventory": { "description": "Boolean value is \"true\" if the product is facilitated by a Booking.com partner company and \"false\" otherwise.", "type": "boolean" } } } }, "recommendation": { "title": "AccommodationsAvailabilityRecommendationOutput", "description": "The products recommended for the provided search criteria.", "type": "object", "properties": { "price": { "title": "AccommodationsRecommendationPrice", "description": "The price components of this product or selection of products. 'base' and 'extra_charges' are returned only when explicitly requested (via 'extras=extra_charges').", "type": "object", "properties": { "base": { "description": "The base price. It does not include any extra charges.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "book": { "description": "The display price that must be shown to the traveller in accordance with local booker protection laws. This price includes the base accommodation cost and all charges that are legally required to be part of the displayed amount. Equivalent to base + charges where included_in.display=true.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "chargeable_online": { "description": "The amount collected by Booking.com from the Virtual Credit Cards (VCCs) when using online payment methods (e.g., pay_online_now, pay_online_later). Equivalent to `base + charges` where `included_in.chargeable_online=true`. Returns `null` for agency-model properties where Booking.com does not process payments.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "extra_charges": { "title": "AccommodationsExtraCharges", "description": "The charge breakdown. Includes taxes and fees.", "type": "object", "properties": { "excluded": { "description": "Charges not included in 'book'.", "type": "number", "format": "double", "minimum": 0 }, "included": { "description": "Charges included in 'book'.", "type": "number", "format": "double", "minimum": 0 } } }, "total": { "description": "The total price. Includes all extra charges.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "products": { "description": "", "type": "array", "items": { "title": "AccommodationsAvailabilityRecommendationProductOutput", "description": "", "type": "object", "properties": { "id": { "description": "Unique ID of the product.", "type": "string" }, "children": { "description": "The ages of the children allocated to this product.", "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17 } }, "number_of_adults": { "description": "The number of adults allocated to this product.", "type": "integer", "minimum": 1 }, "price": { "title": "AccommodationsRecommendationPrice", "description": "The price components of this product or selection of products. 'base' and 'extra_charges' are returned only when explicitly requested (via 'extras=extra_charges').", "type": "object", "properties": { "base": { "description": "The base price. It does not include any extra charges.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "book": { "description": "The display price that must be shown to the traveller in accordance with local booker protection laws. This price includes the base accommodation cost and all charges that are legally required to be part of the displayed amount. Equivalent to base + charges where included_in.display=true.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "chargeable_online": { "description": "The amount collected by Booking.com from the Virtual Credit Cards (VCCs) when using online payment methods (e.g., pay_online_now, pay_online_later). Equivalent to `base + charges` where `included_in.chargeable_online=true`. Returns `null` for agency-model properties where Booking.com does not process payments.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "extra_charges": { "title": "AccommodationsExtraCharges", "description": "The charge breakdown. Includes taxes and fees.", "type": "object", "properties": { "excluded": { "description": "Charges not included in 'book'.", "type": "number", "format": "double", "minimum": 0 }, "included": { "description": "Charges included in 'book'.", "type": "number", "format": "double", "minimum": 0 } } }, "total": { "description": "The total price. Includes all extra charges.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } } } } }, "url": { "description": "Internet address for the property page on Booking.com.", "type": "string", "format": "url" } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": { "id": 10004, "currency": "EUR", "deep_link_url": "booking://hotel/10004?affiliate_id=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!", "products": [ { "id": "1000420_358188572_2_0_0", "bundle": null, "deal": null, "inventory": { "third_party": false, "type": "sell" }, "maximum_occupancy": { "adults": 2, "children": null, "total": 2 }, "number_available_at_this_price": 3, "policies": { "cancellation": { "free_cancellation_until": "!START_DATE-2!T00:00:00+00:00", "type": "free_cancellation" }, "meal_plan": { "meals": [], "plan": "no_plan" }, "payment": { "prepayment_required": false, "timings": [ "pay_at_the_property" ] } }, "price": { "base": 1189.63, "book": 1385.97, "chargeable_online": 1385.97, "extra_charges": { "conditional": [], "excluded": [], "included": [ { "charge": 21, "chargeable_online": true, "mode": "percentage", "percentage": 9, "total_amount": 107.07, "unit_amount": null }, { "charge": 22, "chargeable_online": false, "mode": "percentage", "percentage": 7, "total_amount": 83.27, "unit_amount": null }, { "charge": 142, "chargeable_online": true, "mode": "per_person_per_night", "percentage": null, "total_amount": 6, "unit_amount": 3 } ] }, "total": 1385.97 }, "room": 1000420, "third_party_inventory": false }, "..." ], "recommendation": { "price": { "base": 1081.49, "book": 1260.52, "chargeable_online": 1260.52, "extra_charges": { "excluded": 0, "included": 179.04 }, "total": 1260.52 }, "products": [ { "id": "1000420_95127794_2_0_0", "children": [], "number_of_adults": 2, "price": { "base": 1081.49, "book": 1260.52, "chargeable_online": 1260.52, "extra_charges": { "excluded": 0, "included": 179.04 }, "total": 1260.52 } } ] }, "url": "https://www.booking.com/hotel/nl/toren.html?aid=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!&no_rooms=1&group_adults=2" } } } } } } } }, "/accommodations/bulk-availability": { "post": { "summary": "Check multiple availability", "description": "Retrieve detailed availability, pricing, and charges for **up to 50 accommodation IDs**.\n\n - By default, only availability and price are returned. \n - Use the `extras` parameter to receive additional information.\n\n**Mandatory fields**: `accommodations`, `booker`, `checkin`, `checkout`, and `guests`.'\n", "operationId": "/accommodations/bulk-availability", "parameters": [ { "in": "header", "name": "X-Affiliate-Id", "schema": { "type": "integer" }, "required": true, "description": "Include here your Affiliate identifier number" } ], "tags": [ "Accommodations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "AccommodationsBulkAvailabilityInput", "type": "object", "properties": { "accommodations": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 } }, "booker": { "title": "Booker", "description": "The booker's information.", "type": "object", "properties": { "country": { "description": "The booker country for showing the best price for that user and obeying laws regarding the display of taxes and fees.", "type": "string", "pattern": "^[a-z]{2}$" }, "platform": { "description": "The booker platform for showing the platform based deals and prices.", "type": "string", "enum": [ "android", "desktop", "ios", "mobile", "tablet" ] }, "state": { "description": "The booker state for showing the best price for that user and obeying laws regarding the display of taxes and fees. Currently applicable only for country US.", "type": "string", "pattern": "^[a-z]{2}$" }, "travel_purpose": { "description": "The travel purpose of the booker.", "type": "string", "enum": [ "business", "leisure" ] }, "user_groups": { "description": "The user groups that the booker is a member of.", "type": "array", "items": { "type": "string", "enum": [ "authenticated" ] } } }, "required": [ "country", "platform" ] }, "checkin": { "description": "The checkin date. Must be within 500 days in the future and in the format yyyy-mm-dd.", "type": "string", "format": "date" }, "checkout": { "description": "The checkout date. Must be later than {checkin}. Must be between 1 and 90 days after {checkin}. Must be within 500 days in the future and in the format yyyy-mm-dd.", "type": "string", "format": "date" }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "extras": { "description": "Input parameter to request for additional information about this product. Add \"include_bundle_variants\" to include all bookable products with bundles.", "type": "array", "items": { "type": "string", "enum": [ "extra_charges", "include_bundle_variants" ] } }, "filters": { "title": "AccommodationsBulkAvailabilityFiltersInput", "description": "The filters to apply in this availability request.", "type": "object", "properties": { "cancellation_type": { "description": "Filters the result for the cancellation type specified. Possible values are free_cancellation. The result will contain all the products with free_cancellation.", "type": "string", "enum": [ "free_cancellation" ] }, "meal_plan": { "description": "Filter the result based on the selected meal plan. Example: When specified breakfast_included, it will show the product with free breakfast.", "type": "string", "enum": [ "all_inclusive", "breakfast_included", "full_board", "half_board" ] }, "payment": { "description": "Payment input information to filter results.", "properties": { "timing": { "description": "This parameter specifies that the results should only return accommodation and blocks that contain the specified payment timings.", "type": "string", "enum": [ "pay_at_the_property", "pay_online" ] } } }, "third_party_inventory": { "description": "Whether to include third party inventory in the response", "type": "boolean" } } }, "guests": { "title": "AccommodationsGuests", "description": "The guest details for the request.", "type": "object", "properties": { "allocation": { "description": "The exact allocation of guests to rooms.", "type": "array", "items": { "properties": { "children": { "description": "The children ages for this room.", "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17 } }, "number_of_adults": { "description": "The number of adults for this room.", "type": "integer", "minimum": 1 } }, "required": [ "number_of_adults" ] } }, "children": { "description": "Array with the children ages.", "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17 } }, "number_of_adults": { "description": "The number of adults for the search.", "type": "integer", "minimum": 1 }, "number_of_rooms": { "description": "The number of rooms needed.", "type": "integer", "minimum": 1 } }, "required": [ "number_of_adults", "number_of_rooms" ] } }, "required": [ "accommodations", "booker", "checkin", "checkout", "guests" ] }, "example": { "accommodations": [ 10004 ], "booker": { "country": "nl", "platform": "desktop" }, "checkin": "!START_DATE!", "checkout": "!END_DATE!", "extras": [ "extra_charges" ], "filters": { "meal_plan": "breakfast_included", "cancellation_type": "free_cancellation" }, "guests": { "number_of_adults": 2, "number_of_rooms": 1 } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "AccommodationsBulkAvailabilityOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "AccommodationsBulkAvailabilityDataOutput,", "description": "", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "deep_link_url": { "description": "A mobile app URL that directs the user to a specific page or content within the Booking.com app. The link can only be used on a device with the Booking.com app installed. It typically includes an Affiliate ID (AID) to attribute bookings to the affiliate partner when users are redirected", "type": "string", "format": "url" }, "products": { "type": "array", "items": { "title": "AccommodationsBulkAvailabilityProductOutput", "description": "", "type": "object", "properties": { "id": { "description": "Unique ID of the product.", "type": "string" }, "bundle": { "description": "The bundle ID of the product comprising of value added products.", "type": "integer" }, "deal": { "title": "Deal", "description": "This specifies the deal tagging for the product.", "type": [ "object", "null" ], "properties": { "discount_percentage": { "description": "Discount percentage of the applied deal.", "type": "integer", "minimum": 1 }, "public_price": { "description": "Original price of this product, before applying any discounts.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "tags": { "description": "The tags of all the applied deals.", "type": "array", "items": { "type": "string", "enum": [ "black_friday", "limited_time_deal", "logged_in_deal", "mobile_rate", "seasonal_deal" ] } } } }, "maximum_occupancy": { "title": "AccommodationsMaximumOccupancy", "description": "Information related to maximum number of occupancy inside the room.", "type": "object", "properties": { "adults": { "description": "The maximum number of adults for this room.", "type": "integer", "minimum": 1 }, "children": { "description": "The information about maximum number of children and their allowed ages for this room.", "type": "array", "items": { "title": "AccommodationsChildren", "type": "object", "properties": { "total": { "description": "The maximum number of children for this room.", "type": "integer", "minimum": 1 }, "from_age": { "description": "The youngest age of the children allowed in this room.", "type": "integer", "minimum": 0, "maximum": 17 }, "to_age": { "description": "The oldest age of the children allowed in this room.", "type": "integer", "minimum": 0, "maximum": 17 }, "free_stay": { "description": "Whether children in this age bracket will be staying for free. False indicates their cost was already included in the price.", "type": "boolean" } } } }, "total": { "description": "The maximum number of guests for this room.", "type": "integer", "minimum": 1 } } }, "number_available": { "description": "How many units of this product are still available.", "type": "integer", "minimum": 1 }, "policies": { "title": "AccommodationsProductPolicies", "description": "The policies for this product.", "type": "object", "properties": { "cancellation": { "title": "AccommodationsProductCancellationPolicy", "description": "The cancellation policy for this product.", "type": "object", "properties": { "free_cancellation_until": { "description": "Until when the order for this product can be cancelled for free.", "type": [ "string", "null" ], "format": "date-time" }, "schedule": { "description": "The cancellation policy schedule for this product.", "type": "array", "items": { "title": "AccommodationsProductDetailedCancellationPolicy", "type": "object", "properties": { "from": { "description": "The time from which this cancellation fee applies. `now` means from booking time.", "type": [ "string", "null" ], "oneOf": [ { "format": "date-time" }, { "pattern": "now" } ] }, "price": { "description": "The cancellation fee.", "type": "number", "format": "double", "minimum": 0 } } } }, "type": { "description": "The cancellation policy applicable to this product: \"free_cancellation\" allows a period for free cancellation, \"non_refundable\" means immediate loss of total amount, \"special_conditions\" means partly refundable.", "type": "string", "enum": [ "free_cancellation", "non_refundable", "special_conditions" ] } } }, "meal_plan": { "title": "AccommodationsProductMealPlanPolicy", "description": "The meal plan policy for this product.", "type": "object", "properties": { "meals": { "description": "The meals included in the meal plan.", "type": "array", "items": { "type": "string", "enum": [ "breakfast", "dinner", "lunch" ] } }, "plan": { "description": "The meal plan included in this product.", "type": "string", "enum": [ "all_inclusive", "breakfast_included", "full_board", "half_board", "no_plan" ] } } }, "payment": { "title": "AccommodationsProductPaymentPolicyNew", "description": "Payment terms and conditions for this product.", "type": "object", "properties": { "prepayment_required": { "description": "Whether prepayment is required for this product.", "type": "boolean" }, "timings": { "description": "The payment timings supported by this product.", "type": "array", "items": { "type": "string", "enum": [ "pay_at_the_property", "pay_online_later", "pay_online_now" ] } } } } } }, "price": { "title": "AccommodationsAvailabilityProductPrice", "description": "The price components of this product. 'base' and 'extra_charges' are returned only when explicitly requested (via 'extras=extra_charges').", "type": "object", "properties": { "base": { "description": "The base price. It does not include any extra charges.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "book": { "description": "The display price that must be shown to the traveller under local booker protection laws. This price includes the base accommodation cost and all charges that are legally required to be part of the displayed price. Equivalent to base + included charges.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "chargeable_online": { "description": "The price that will be charged by Booking.com when online payments are used. This field does not apply to the \"pay_at_the_property\" timing.", "nullable": true, "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "extra_charges": { "title": "AccommodationsProductExtraCharges", "description": "The charge breakdown. Includes taxes and fees.", "type": "object", "properties": { "conditional": { "description": "Charges that might apply under a specific condition.", "type": "array", "items": { "title": "AccommodationsConditionalCharge", "description": "Charges that might apply under a specific condition.", "type": "object", "properties": { "charge": { "description": "A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 0 }, "condition": { "description": "A signed integer number that uniquely identifies the condition ID. Find the full list in the Pricing guidelines.", "type": [ "integer", "null" ], "minimum": 0 }, "mode": { "description": "The mode of this charge. Determines how the price is calculated.", "type": "string", "enum": [ "calculated_amount", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay" ] }, "percentage": { "description": "The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "total_amount": { "description": "The total price for this charge.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "unit_amount": { "description": "The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true } } } }, "excluded": { "description": "Charges not included in 'book'.", "type": "array", "items": { "title": "AccommodationsAvailabilityCharge", "description": "All non-conditional charges that will necessarily be paid", "type": "object", "properties": { "charge": { "description": "A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 0 }, "chargeable_online": { "description": "Whether this charge is chargeable online or not. Not applicable to \"pay_at_the_property\" timing.", "type": "boolean", "nullable": true }, "mode": { "description": "The mode of this charge. Determines how the price is calculated.", "type": "string", "enum": [ "calculated_amount", "incalculable", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay" ] }, "percentage": { "description": "The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "total_amount": { "description": "The total price for this charge.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "unit_amount": { "description": "The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true } } } }, "included": { "description": "Charges included in 'book'.", "type": "array", "items": { "title": "AccommodationsAvailabilityCharge", "description": "All non-conditional charges that will necessarily be paid", "type": "object", "properties": { "charge": { "description": "A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 0 }, "chargeable_online": { "description": "Whether this charge is chargeable online or not. Not applicable to \"pay_at_the_property\" timing.", "type": "boolean", "nullable": true }, "mode": { "description": "The mode of this charge. Determines how the price is calculated.", "type": "string", "enum": [ "calculated_amount", "incalculable", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay" ] }, "percentage": { "description": "The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "total_amount": { "description": "The total price for this charge.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "unit_amount": { "description": "The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true } } } } } }, "total": { "description": "The total price. Includes all extra charges.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "room": { "description": "A signed integer number that uniquely identifies an accommodation property room. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "third_party_inventory": { "description": "Boolean value is \"true\" if the product is facilitated by a Booking.com partner company and \"false\" otherwise.", "type": "boolean" } } } }, "recommendation": { "title": "AccommodationsBulkAvailabilityRecommendationOutput", "description": "The products recommended for the provided search criteria.", "type": "object", "properties": { "price": { "title": "AccommodationsRecommendationPrice", "description": "The price components of this product or selection of products. 'base' and 'extra_charges' are returned only when explicitly requested (via 'extras=extra_charges').", "type": "object", "properties": { "base": { "description": "The base price. It does not include any extra charges.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "book": { "description": "The display price that must be shown to the traveller in accordance with local booker protection laws. This price includes the base accommodation cost and all charges that are legally required to be part of the displayed amount. Equivalent to base + charges where included_in.display=true.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "chargeable_online": { "description": "The amount collected by Booking.com from the Virtual Credit Cards (VCCs) when using online payment methods (e.g., pay_online_now, pay_online_later). Equivalent to `base + charges` where `included_in.chargeable_online=true`. Returns `null` for agency-model properties where Booking.com does not process payments.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "extra_charges": { "title": "AccommodationsExtraCharges", "description": "The charge breakdown. Includes taxes and fees.", "type": "object", "properties": { "excluded": { "description": "Charges not included in 'book'.", "type": "number", "format": "double", "minimum": 0 }, "included": { "description": "Charges included in 'book'.", "type": "number", "format": "double", "minimum": 0 } } }, "total": { "description": "The total price. Includes all extra charges.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "products": { "description": "", "type": "array", "items": { "title": "AccommodationsAvailabilityRecommendationProductOutput", "description": "", "type": "object", "properties": { "id": { "description": "Unique ID of the product.", "type": "string" }, "children": { "description": "The ages of the children allocated to this product.", "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17 } }, "number_of_adults": { "description": "The number of adults allocated to this product.", "type": "integer", "minimum": 1 }, "price": { "title": "AccommodationsRecommendationPrice", "description": "The price components of this product or selection of products. 'base' and 'extra_charges' are returned only when explicitly requested (via 'extras=extra_charges').", "type": "object", "properties": { "base": { "description": "The base price. It does not include any extra charges.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "book": { "description": "The display price that must be shown to the traveller in accordance with local booker protection laws. This price includes the base accommodation cost and all charges that are legally required to be part of the displayed amount. Equivalent to base + charges where included_in.display=true.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "chargeable_online": { "description": "The amount collected by Booking.com from the Virtual Credit Cards (VCCs) when using online payment methods (e.g., pay_online_now, pay_online_later). Equivalent to `base + charges` where `included_in.chargeable_online=true`. Returns `null` for agency-model properties where Booking.com does not process payments.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "extra_charges": { "title": "AccommodationsExtraCharges", "description": "The charge breakdown. Includes taxes and fees.", "type": "object", "properties": { "excluded": { "description": "Charges not included in 'book'.", "type": "number", "format": "double", "minimum": 0 }, "included": { "description": "Charges included in 'book'.", "type": "number", "format": "double", "minimum": 0 } } }, "total": { "description": "The total price. Includes all extra charges.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } } } } }, "url": { "description": "Internet address for the property page on Booking.com.", "type": "string", "format": "url" } } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 10004, "currency": "EUR", "deep_link_url": "booking://hotel/10004?affiliate_id=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!", "products": [ { "id": "1000420_358188572_2_0_0", "bundle": null, "deal": null, "maximum_occupancy": { "adults": 2, "children": null, "total": 2 }, "number_available": 3, "policies": { "cancellation": { "free_cancellation_until": "!START_DATE-2!T00:00:00+00:00", "type": "free_cancellation", "schedule": [ { "from": "now", "price": 0 }, { "from": "!START_DATE-2!T00:00:00+00:00", "price": 1189.63 } ] }, "meal_plan": { "meals": [], "plan": "no_plan" }, "payment": { "timings": [ "pay_at_the_property" ] } }, "price": { "base": 1189.63, "book": 1385.97, "chargeable_online": 1385.97, "extra_charges": { "conditional": [], "excluded": [], "included": [ { "charge": 21, "chargeable_online": true, "mode": "percentage", "percentage": 9, "total_amount": 107.07, "unit_amount": null }, { "charge": 22, "chargeable_online": false, "mode": "percentage", "percentage": 7, "total_amount": 83.27, "unit_amount": null }, { "charge": 142, "chargeable_online": true, "mode": "per_person_per_night", "percentage": null, "total_amount": 6, "unit_amount": 3 } ] }, "total": 1385.97 }, "room": 1000420, "third_party_inventory": true }, "..." ], "recommendation": { "price": { "base": 1081.49, "book": 1260.52, "chargeable_online": 1260.52, "extra_charges": { "excluded": 0, "included": 179.04 }, "total": 1260.52 }, "products": [ { "id": "1000420_95127794_2_0_0", "children": [], "number_of_adults": 2, "price": { "base": 1081.49, "book": 1260.52, "chargeable_online": 1260.52, "extra_charges": { "excluded": 0, "included": 179.04 }, "total": 1260.52 } } ] }, "url": "https://www.booking.com/hotel/nl/toren.html?aid=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!&no_rooms=1&group_adults=2" } ] } } } } } } }, "/accommodations/chains": { "post": { "summary": "Chains", "description": "Use this endpoint to retrieve a list of accommodation chains and their associated brands.

A chain-branded accommodation is part of a larger corporate group and operates under a recognised brand. The returned information can be used to filter search results by chain or brand across other endpoints.
- To obtain the full list of chains, call this endpoint with an empty request body.
- The `id` values returned are the codes used as input and output in other API requests, ensuring consistency across your integration.
**Example of chain** - \"Radisson Hotel Group\" with brands such as \"Radisson Blu\" or \"Park Inn by Radisson.\"", "operationId": "/accommodations/chains", "parameters": [ { "in": "header", "name": "X-Affiliate-Id", "schema": { "type": "integer" }, "required": true, "description": "Include here your Affiliate identifier number" } ], "tags": [ "Accommodations" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "AccommodationsChainsBrandOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "AccommodationsChainsOutput", "description": "Returns the internal code, name and list of associated brands for an accommodation chain.", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation chain. Examples of chains are: Radisson Hotel Group, Hilton Worldwide etc. The full list can be obtained by calling /accommodations/chains.", "type": "integer", "minimum": 1 }, "brands": { "description": "List of all the brands associated with this accommodation chain.", "type": "array", "items": { "title": "AccommodationsChainsBrandDataOutput", "description": "Returns the internal code and name of an accommodation brand.", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation brand. Examples of brands are: Radisson Blu, WestCord Hotels, Westin etc. The full list can be obtained by calling /accommodations/chains.", "type": "integer", "minimum": 1 }, "name": { "description": "Name of the accommodation brand.", "type": "string" } } } }, "name": { "description": "Name of the accommodation chain.", "type": "string" } } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 3, "brands": [ { "id": 1018, "name": "Campanile" }, "..." ], "name": "Louvre Hotels Group" }, "..." ] } } } } } } }, "/accommodations/constants": { "post": { "summary": "Constants", "description": "Use this endpoint to retrieve standardised codes and names for accommodation-specific types, including facilities, room types, bed types, themes, and charges.
These constants can be used to filter searches or populate reference data across other accommodation endpoints.
You can request multiple languages using IETF language tags (see common/languages).
Call with an empty body to retrieve all constants. The codes returned are canonical identifiers used across the API.", "operationId": "/accommodations/constants", "parameters": [ { "in": "header", "name": "X-Affiliate-Id", "schema": { "type": "integer" }, "required": true, "description": "Include here your Affiliate identifier number" } ], "tags": [ "Accommodations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "AccommodationsConstantsInput", "type": "object", "properties": { "constants": { "description": "Allows to filter the results only for specific sections.", "type": "array", "items": { "type": "string", "enum": [ "accommodation_facilities", "accommodation_themes", "accommodation_types", "bed_types", "charge_types", "facility_types", "review_scores", "room_facilities", "room_types" ] } }, "languages": { "type": "array", "items": { "description": "A [IETF language tag code](https://en.wikipedia.org/wiki/IETF_language_tag) that uniquely identifies a supported human language or dialect. **Note:** Demand API only accepts lowercase for the language codes. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "default": [ "en-gb" ] } } }, "example": { "languages": [ "en-gb", "zh-cn" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "AccommodationsConstantsOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "title": "ConstantsDataOutput", "type": "object", "properties": { "accommodation_facilities": { "type": "array", "items": { "title": "AccommodationsFacilityOutput", "description": "A service, equipment or characteristic available at property level, like for example: \"Swimming pool outdoor\".", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property facility. Examples of facilities are: Parking, Restaurant, Room service etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 }, "facility_type": { "description": "A signed integer number that uniquely identifies the accommodation facility type. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } } }, "accommodation_themes": { "type": "array", "items": { "title": "AccommodationsThemeOutput", "description": "Accommodations can be grouped in \"themes\" depending on their characteristics. For example: \"Beach/Seaside\".", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property theme. Examples of themes are: Beach/Seaside, Ski/Wintersports, Luxury etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } } }, "accommodation_types": { "type": "array", "items": { "title": "AccommodationsTypeOutput", "description": "The type of an accommodation. Examples of types are \"Hotel\", \"Apartment\", etc.", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property type. Examples of accommodation types are: Apartment, Hostel, Hotel etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } } }, "bed_types": { "type": "array", "items": { "title": "AccommodationsBedTypeOutput", "description": "", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies a bed type. Examples of bed types are: Single, Double etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 }, "description": { "description": "Translated description of the bed size in metric.", "title": "TranslatedString", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "description_imperial": { "description": "Translated description of the bed size in imperial.", "title": "TranslatedString", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "name": { "description": "Translated name of the bed type.", "title": "TranslatedString", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } } }, "charge_types": { "type": "array", "items": { "title": "AccommodationsChargeTypeOutput", "description": "These are additional charges, which may be included or excluded from the reservation price. If excluded, the amounts may be added by the property upon checkout. The exclusions depend on several factors like local legislation, and sometimes can only be indicated but not be calculated at the time of the reservation.", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 0 }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } } }, "facility_types": { "type": "array", "items": { "title": "AccommodationsFacilityTypeOutput", "description": "A more generic designation meant to group a set of facilities.", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies the accommodation facility type. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } } }, "review_scores": { "type": "array", "items": { "title": "AccommodationsReviewScoreOutput", "description": "Review score category name for each score interval.", "type": "object", "properties": { "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "minimum_score": { "description": "The minimum score of this review score category.", "type": "number", "multipleOf": 0.1, "minimum": 1, "maximum": 10 }, "maximum_score": { "description": "The maximum score of this review score category", "type": "number", "multipleOf": 0.1, "minimum": 1, "maximum": 10 } } } }, "room_facilities": { "type": "array", "items": { "title": "AccommodationsRoomFacilityOutput", "description": "A service, equipment or characteristic available at room level, like for example: \"Coffee/Tea maker\".", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property room facility. Examples of facilities are: Coffee/Tea maker, TV, Airconditioning, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 }, "facility_type": { "description": "A signed integer number that uniquely identifies the accommodation facility type. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } } }, "room_types": { "type": "array", "items": { "title": "AccommodationsRoomTypeOutput", "description": "Designations for different types of rooms, based on topology and/or setup. Examples: \"Twin/Double\" or \"Dormitory room\".", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property room type. Example of room types are: Suite, Apartment, Twin/Double etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } } } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": { "accommodation_facilities": [ { "id": 2, "facility_type": 16, "name": { "en-gb": "Parking", "zh-cn": "停车场" } }, "..." ], "accommodation_themes": [ { "id": 1, "name": { "en-gb": "Apartments", "zh-cn": "公寓" } }, "..." ], "accommodation_types": [ { "id": 201, "name": { "en-gb": "Apartment", "zh-cn": "公寓" } }, "..." ], "bed_types": [ { "id": 1, "description": { "en-gb": "90-130 cm wide", "zh-cn": "宽 90-130 厘米" }, "description_imperial": { "en-gb": "35-51 inches wide", "zh-cn": "宽 35-51 英寸" }, "name": { "en-gb": "Single bed(s)", "zh-cn": "单人床" } }, "..." ], "charge_types": [ { "id": 0, "name": { "en-gb": "service charge", "zh-cn": "服务费" } }, "..." ], "facility_types": [ { "id": 1, "name": { "en-gb": "General", "zh-cn": "综合设施" } }, "..." ], "review_scores": [ { "maximum_score": 2.9, "minimum_score": 2, "name": { "en-gb": "very poor", "zh-cn": "非常差" } }, "..." ], "room_facilities": [ { "id": 1, "facility_type": 7, "name": { "en-gb": "Coffee/Tea maker", "zh-cn": "沏茶/咖啡设备" } }, "..." ], "room_types": [ { "id": 1, "name": { "en-gb": "Apartment", "zh-cn": "公寓" } }, "..." ] } } } } } } } }, "/accommodations/details": { "post": { "summary": "Details", "description": "This endpoint returns detailed information on all accommodation properties matching a given search criteria. By default, only basic information is returned.

It is mandatory to pass one of the input parameters: accommodations, airport, city, country or region.

To receive extended information use the `extras` parameter.", "operationId": "/accommodations/details", "parameters": [ { "in": "header", "name": "X-Affiliate-Id", "schema": { "type": "integer" }, "required": true, "description": "Include here your Affiliate identifier number" } ], "tags": [ "Accommodations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "AccommodationsDetailsInput", "type": "object", "properties": { "accommodation_facilities": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation property facility. Examples of facilities are: Parking, Restaurant, Room service etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 } }, "accommodation_types": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation property type. Examples of accommodation types are: Apartment, Hostel, Hotel etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 } }, "accommodations": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "maxItems": 100 }, "airport": { "description": "A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling common/locations/airports.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "AMS" }, "brands": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation brand. Examples of brands are: Radisson Blu, WestCord Hotels, Westin etc. The full list can be obtained by calling /accommodations/chains.", "type": "integer", "minimum": 1 } }, "city": { "description": "A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.", "type": "integer" }, "country": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "extras": { "description": "Input parameter to request for additional information about the accommodation property. It should be passed as a JSON array with one or more items.", "type": "array", "items": { "type": "string", "enum": [ "description", "bundles", "facilities", "payment", "photos", "policies", "rooms" ] } }, "languages": { "type": "array", "items": { "description": "A [IETF language tag code](https://en.wikipedia.org/wiki/IETF_language_tag) that uniquely identifies a supported human language or dialect. **Note:** Demand API only accepts lowercase for the language codes. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" } }, "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" }, "payment": { "description": "Payment input information to filter results.", "properties": { "timing": { "description": "This parameter specifies that the results should only return accommodation and blocks that contain the specified payment timings.", "type": "string", "enum": [ "pay_at_the_property", "pay_online" ] } } }, "region": { "description": "A signed integer number that uniquely identifies a geographical region. Regions usually define official administrative areas within a country, but may also include multiple countries and in some cases un-official but popular designations for geographical areas. An example of a region that crosses multiple countries is the Alps in Europe. The full list can be obtained by calling common/locations/regions.", "type": "integer", "minimum": 1 }, "rows": { "maximum": 1000, "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "default": 100 } } }, "example": { "accommodations": [ 10004 ], "extras": [ "bundles", "description", "facilities", "payment", "photos", "policies", "rooms" ], "languages": [ "en-gb", "zh-cn" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "AccommodationsDetailsOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "AccommodationsDetailsDataOutput", "description": "All static information related to an accommodation property (excludes information on availability).", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "accommodation_type": { "description": "A signed integer number that uniquely identifies an accommodation property type. Examples of accommodation types are: Apartment, Hostel, Hotel etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 }, "booker_address_required": { "description": "A boolean indicating whether a booker address is required for the property. If true, a booker address must be provided in the orders/create endpoint. If false, the booker address is not required and can be omitted from the orders/create endpoint.", "type": "boolean" }, "brands": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation brand. Examples of brands are: Radisson Blu, WestCord Hotels, Westin etc. The full list can be obtained by calling /accommodations/chains.", "type": "integer", "minimum": 1 } }, "bundles": { "title": "BundlesTranslatedOutput", "description": "List of value-added bundles offered by this accommodation. Each bundle groups one or more value-added benefits that are included with the stay, such as complimentary services, credits, or special amenities. Bundles are informational only. They cannot be selected, filtered, or booked independently and do not represent a separate rate or product. This field is returned only when `bundles` is included in the `extras` request parameter.", "type": "array", "items": { "title": "BundleTranslatedOutput", "type": "object", "description": "A group of value-added benefits included with the accommodation.", "properties": { "id": { "type": "integer", "description": "Unique identifier of the bundle." }, "value_adds": { "type": "array", "description": "List of value-added benefits included in this bundle. Each value-add represents a single benefit and includes localised descriptive text for display purposes.", "items": { "title": "ValueAddTranslatedOutput", "type": "object", "description": "A single value-added benefit included in the bundle, with its type and descriptive text localised in multiple languages.", "properties": { "type": { "description": "Identifies the type of value-added benefit included in the bundle, such as complimentary services, monetary credits, percentage discounts, or experiential amenities. Enum values encode how the benefit is applied, including time scope (per day or per stay) and unit scope (per room or per adult).", "type": "string", "enum": [ "parking", "food_drink_credit_per_day_per_room", "food_drink_credit_per_day_per_adult", "property_credit_per_day_per_room", "food_drink_credit_per_stay_per_adult", "food_drink_credit_per_stay_per_room", "property_credit_per_day_per_adult", "property_credit_per_stay_per_adult", "property_credit_per_stay_per_room", "food_drink_discount", "property_discount", "early_checkin", "late_checkout", "late_checkin", "spa_daily", "spa_hourly", "spa_massage", "high_speed_internet", "airport_transfer", "safari_game_drive", "safari_walk", "pets_stay", "bottle_of_wine", "bottle_of_champagne", "park_sleep_fly" ] }, "description": { "title": "TranslatedStringArray", "description": "List of descriptive text lines for the value-added service, localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "array", "null" ], "items": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } } } } } } } } }, "checkin_checkout_times": { "title": "AccommodationsCheckinCheckoutTimesOutput", "type": "object", "properties": { "checkin_from": { "description": "The time from when checkin starts at this property.", "type": [ "string", "null" ], "pattern": "(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]:00" }, "checkin_to": { "description": "The time till when checkin can be done at this property.", "type": [ "string", "null" ], "pattern": "(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]:00" }, "checkout_from": { "description": "The time from when checkout starts at this property.", "type": [ "string", "null" ], "pattern": "(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]:00" }, "checkout_to": { "description": "The time till when checkout can be done at this property.", "type": [ "string", "null" ], "pattern": "(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]:00" } } }, "contacts": { "title": "AccommodationsContactsOutput", "description": "Contact information of the accommodation.", "type": "object", "properties": { "general": { "title": "AccommodationsContactOutput", "description": "Contact information of the accommodation. It can be `null` if the data is missing.", "type": "object", "properties": { "email": { "description": "Email address of the accommodation. It can be `null` if the data is missing.", "type": [ "string", "null" ] }, "telephone": { "description": "Telephone number of the accommodation. It can be `null` if the data is missing.", "type": [ "string", "null" ] } }, "nullable": true }, "reservations": { "title": "AccommodationsContactOutput", "description": "Contact information of the accommodation. It can be `null` if the data is missing.", "type": "object", "properties": { "email": { "description": "Email address of the accommodation. It can be `null` if the data is missing.", "type": "string", "nullable": true }, "telephone": { "description": "Telephone number of the accommodation. It can be `null` if the data is missing.", "type": "string", "nullable": true } }, "nullable": true } } }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "deep_link_url": { "description": "A mobile app URL that directs the user to a specific page or content within the Booking.com app. The link can only be used on a device with the Booking.com app installed. It typically includes an Affiliate ID (AID) to attribute bookings to the affiliate partner when users are redirected", "type": "string", "format": "url" }, "description": { "title": "AccommodationsDescriptionOutput", "description": "Textual information about the accommodation. Requires `{\"extras\":[\"description\"]}`.", "type": "object", "properties": { "host_type": { "description": "Type of host.", "type": "string", "enum": [ "private", "professional", "unknown" ] }, "important_information": { "description": "Text containing important information about the property. The value is translated in the requested languages.", "title": "TranslatedString", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "license_numbers": { "description": "List of all the license numbers of this accommodation property.", "type": "array", "nullable": true, "items": { "type": "string" } }, "text": { "description": "The translated description text of this accommodation property in the requested languages. The maximum number of characters returned may be limited by contract.", "title": "TranslatedString", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "trader": { "title": "TraderOutput", "description": "The trader information.", "type": "object", "nullable": true, "properties": { "address": { "description": "The address of the trader", "title": "AccommodationsAddress", "type": "object", "properties": { "address_line": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "post_code": { "type": "string" } } }, "email": { "description": "The email of the trader", "type": "string" }, "name": { "description": "The name of the trader", "type": "string" }, "registration_number": { "description": "The registration number of the trader", "type": "string" }, "telephone": { "description": "The telephone of the trader", "type": "string" }, "trade_register": { "description": "The trade register name", "type": "string" }, "trader_verified": { "description": "Indicates whether the trader has successfully met Booking.com's internal verification process, based on established criteria and checklists", "type": "boolean" } } } } }, "facilities": { "description": "The list of facilities available in this property. Requires `{\"extras\":[\"facilities\"]}`.", "type": "array", "items": { "title": "AccommodationsFacilityOutput", "description": "Facility information for the accommodation.", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property facility. Examples of facilities are: Parking, Restaurant, Room service etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 }, "attributes": { "type": "array", "items": { "description": "List of optional attributes for this facility.", "type": "string", "enum": [ "offsite", "paid" ] } } } } }, "facility_details": { "description": "Provides detailed information about the facilities available at the accommodation. This data is accessible by including `{\"extras\":[\"facilities\"]}` in the request.", "title": "accommodationsFacilityDetailsOutput", "type": "object", "properties": { "internet_facility": { "description": "Details about the internet facilities available at the accommodation, including price, charge mode and connection type.", "type": "object", "title": "AccommodationsInternetFacilityOutput", "properties": { "charge_mode": { "type": "string", "description": "The charging model for internet access at the accommodation.", "nullable": true, "enum": [ "charges_are_applicable", "free", "per_day", "per_half_hour", "per_hour", "per_minute" ] }, "connection_type": { "type": "string", "description": "The type of internet connection available, whether wireless (Wi-Fi) or wired.", "nullable": true, "enum": [ "wifi", "wired" ] }, "coverage": { "type": "string", "description": "The extent of the internet coverage within the accommodation, indicating the areas where internet access is available.", "nullable": true, "enum": [ "all_rooms", "business_center", "entire_property", "public_areas", "some_rooms" ] }, "price": { "description": "The price for using the internet facility, if applicable.", "minimum": 0, "nullable": true, "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "parking_facilities": { "type": "array", "description": "A list of parking facilities available at the accommodation.", "items": { "title": "AccommodationsParkingFacilityOutput", "description": "Information about the parking facilities available at the accommodation, including pricing, type, location, and reservation requirements.", "type": "object", "properties": { "charge_mode": { "type": "string", "description": "The charging model for parking, such as per hour, per day, or free.", "nullable": true, "enum": [ "free", "charges_are_applicable", "charges_may_apply", "per_hour", "per_day", "per_week", "per_stay" ] }, "location": { "type": "string", "description": "The location of the parking facility relative to the accommodation (on-site or nearby).", "nullable": true, "enum": [ "on_site", "nearby" ] }, "price": { "description": "The price for using the parking facility, if applicable.", "minimum": 0, "nullable": true, "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "reservation": { "type": "string", "description": "Indicates whether a reservation is required for parking at the accommodation.", "nullable": true, "enum": [ "needed", "not_needed", "not_possible" ] }, "type": { "type": "string", "description": "The type of parking available, either public or private.", "nullable": true, "enum": [ "private", "public" ] } } } }, "restaurant_facilities": { "type": "array", "description": "A list of restaurant facilities available at the accommodation.", "items": { "title": "AccommodationsRestaurantFacilityOutput", "description": "Information about the restaurant facilities available at the accommodation.", "type": "object", "properties": { "accept_reservations": { "description": "Indicates whether the restaurant accepts reservations.", "type": "boolean" }, "guests_only": { "description": "Indicates whether the restaurant is exclusive to guests or open to the public.", "type": "boolean" }, "name": { "type": "string", "description": "The name of the restaurant." }, "status": { "type": "string", "description": "The operational status of the restaurant (e.g., open or closed).", "nullable": true, "enum": [ "closed", "open" ] } } } }, "swimming_pool_facilities": { "type": "array", "description": "A list of swimming pool facilities available at the accommodation.", "items": { "title": "AccommodationsSwimmingPoolFacilityOutput", "description": "Details about the swimming pool occupancy limits and options.", "type": "object", "properties": { "allowed_age_type": { "type": "string", "description": "The age group allowed to use the swimming pool (e.g., adults only, all ages, or kids only).", "nullable": true, "enum": [ "adults_only", "all_ages", "kids_only" ] }, "payment_type": { "type": "string", "description": "The payment model for pool access, either free or paid.", "nullable": true, "enum": [ "free", "paid" ] }, "type": { "type": "string", "description": "The type of swimming pool (indoor, outdoor, or a combination).", "nullable": true, "enum": [ "indoor", "indoor_and_outdoor", "outdoor" ] } } } } } }, "fiscal_information": { "title": "AccommodationsFiscalInformationOutput", "description": "All fiscal related information of this accommodation property.", "type": "object", "properties": { "legal_name": { "type": "string" }, "vat_number": { "type": "string" } } }, "is_genius": { "description": "Whether the accommodation is genius.", "type": "boolean" }, "is_work_friendly": { "description": "**DEPRECATED**, Flags if this accommodation is work friendly.", "type": "boolean", "deprecated": true }, "key_collection_information": { "title": "AccommodationsKeyCollectionInformationOutput", "type": "object", "properties": { "alternate_location": { "title": "AlternateLocationOutput", "description": "Alternate location to collect the key of this accommodation property. This is returned if the key to access the property is in another location.", "type": "object", "properties": { "address": { "type": "string" }, "city": { "type": "string" }, "postal_code": { "type": "string" } } }, "checkin_method": { "description": "An enumeration that describes the conditions for the checkin process and for collecting the key to access the property. This is typically relevant for non-hotel accommodations (like houses or apartments) without a 24 hours front-desk.", "type": "string", "enum": [ "door_code", "lock_box", "reception", "secret_spot", "someone_will_meet", "unknown" ] }, "key_location": { "description": "Location of the key to access this accommodation property.", "type": "string", "enum": [ "at_the_property", "different_place", "unknown" ] } } }, "location": { "title": "AccommodationsLocationOutput", "description": "All location related information of this accommodation property.", "type": "object", "properties": { "address": { "description": "Translated accommodation address.", "title": "TranslatedString", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "city": { "description": "A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.", "type": "integer" }, "coordinates": { "title": "Coordinates", "type": "object", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } } }, "country": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "districts": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies a district. Typically, districts define known areas within a city. The full list can be obtained by calling common/locations/districts.", "type": "integer", "minimum": 1 } }, "postal_code": { "type": "string" }, "regions": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies a geographical region. Regions usually define official administrative areas within a country, but may also include multiple countries and in some cases un-official but popular designations for geographical areas. An example of a region that crosses multiple countries is the Alps in Europe. The full list can be obtained by calling common/locations/regions.", "type": "integer", "minimum": 1 } } } }, "long_stay_friendly_home": { "description": "Whether the accommodation is long stay friendly. Applicable only for homes.", "type": "boolean" }, "meal_prices": { "title": "MealPrices", "description": "Details regarding the meal pricing options offered at this accommodation.", "type": "object", "properties": { "breakfast": { "description": "The price of breakfast per person, expressed in the accommodation's local currency. If the value is null, it indicates that breakfast pricing is not available.", "type": "number", "minimum": 0, "nullable": true }, "dinner": { "description": "The price of dinner per person, expressed in the accommodation's local currency. If the value is null, it indicates that dinner pricing is not available.", "type": "number", "minimum": 0, "nullable": true }, "lunch": { "description": "The price of lunch per person, expressed in the accommodation's local currency. If the value is null, it indicates that lunch pricing is not available.", "type": "number", "minimum": 0, "nullable": true } } }, "name": { "description": "Translated name of the accommodation property.", "title": "TranslatedString", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "number_of_rooms": { "description": "Total number of rooms in the property. Please note that this is not an availability call and that this number is mostly used to determine the size and type of a property.", "type": "integer", "minimum": 0 }, "payment": { "title": "AccommodationsPaymentOutput", "description": "Payment information related to this property. Requires `{\"extras\":[\"payment\"]}`.", "type": "object", "properties": { "methods": { "title": "AccommodationsDetailsPaymentMethodsOutput", "description": "Payment methods accepted by this property.", "type": "object", "properties": { "cards": { "description": "Credit cards accepted when paying at the property", "type": "array", "items": { "description": "A signed integer number that uniquely identifies a payment type. Examples of payment types are the different credit and debit cards. The full list can be obtained by calling common/payments/cards.", "type": "integer", "minimum": 1 } }, "cash": { "description": "Whether this property accepts cash", "type": "boolean", "example": true }, "virtual_cards": { "description": "Virtual credit cards accepted when paying at the property", "type": "array", "items": { "description": "A signed integer number that uniquely identifies a payment type. Examples of payment types are the different credit and debit cards. The full list can be obtained by calling common/payments/cards.", "type": "integer", "minimum": 1 } } } }, "timings": { "description": "The payment timings supported by this product.", "type": "array", "items": { "type": "string", "enum": [ "pay_at_the_property", "pay_online_later", "pay_online_now" ] } }, "cvc_required": { "description": "Whether cvc is mandatory for creating order for this accommodation.", "type": "boolean" }, "domestic_no_cc": { "description": "Whether domestic bookers can book without credit card for products with free cancellation policies.", "type": "boolean" }, "amex_cvc_required": { "description": "If amex card is used as payment method to create order for this accommodation, whether cvc is mandatory for that.", "type": "boolean" } } }, "photos": { "description": "List of photos for this accommodation property. The maximum number of photos returned may be limited by contract. Requires `{\"extras\":[\"photos\"]}`. The photos are returned in no particular order.", "type": "array", "items": { "title": "AccommodationsPhotoOutput", "type": "object", "properties": { "main_photo": { "description": "Flags this as the main photo. Not returned otherwise.", "type": "boolean", "example": true }, "tags": { "type": "array", "items": { "description": "A list of tags associated with the photo. Manually generated.", "type": "string", "example": "Bathroom" } }, "url": { "title": "AccommodationsPhotoUrlOutput", "type": "object", "properties": { "large": { "description": "URL of the photo image with a maximum width of 1280 pixels.", "type": "string", "format": "url", "example": "https://q-xx.bstatic.com/xdata/images/hotel/max1280/20934654.jpg?k=806399263699a47361bdbbefc9c872a3db03eea26c4a815f5f4df95c93e38cdb&o=" }, "standard": { "description": "URL of the photo image with a maximum width of 500 pixels.", "type": "string", "format": "url", "example": "https://q-xx.bstatic.com/xdata/images/hotel/max500/20934654.jpg?k=806399263699a47361bdbbefc9c872a3db03eea26c4a815f5f4df95c93e38cdb&o=" }, "thumbnail": { "description": "URL of the photo thumbnail image with dimensions 100x100 pixels.", "type": "string", "format": "url", "example": "https://q-xx.bstatic.com/xdata/images/hotel/100x100/20934654.jpg?k=806399263699a47361bdbbefc9c872a3db03eea26c4a815f5f4df95c93e38cdb&o=" }, "thumbnail_large": { "description": "URL of the photo thumbnail image with dimensions 300x300 pixels.", "type": "string", "format": "url", "example": "https://q-xx.bstatic.com/xdata/images/hotel/300x300/20934654.jpg?k=806399263699a47361bdbbefc9c872a3db03eea26c4a815f5f4df95c93e38cdb&o=" } } } } } }, "policies": { "title": "AccommodationsPoliciesOutput", "description": "Set of price relevant rules, options and constraints defined by the accommodation for this product. Requires `{\"extras\":[\"policies\"]}`.", "type": "object", "properties": { "cots_and_extra_beds": { "description": "Prices for cots and extra beds.", "type": "array", "items": { "title": "PoliciesCotsAndExtraBedsOutput", "type": "object", "properties": { "age": { "title": "AccommodationsPoliciesAgeOutput", "description": "Ages to which this entry is applicable. Children are aged 0-17. 18/null means adult. The interval is inclusive.", "type": "object", "properties": { "from": { "type": "integer", "minimum": 0, "maximum": 18 }, "to": { "type": "integer", "minimum": 0, "maximum": 18, "nullable": true } } }, "mode": { "description": "How the price is applied per cot/extra bed.", "type": "string", "enum": [ "per_night", "per_stay" ] }, "percentage": { "description": "Non-null when the price is a percentage.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "price": { "description": "Non-null when the price is fixed or free.", "minimum": 0, "nullable": true, "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "type": { "description": "Whether this entry relates to a cot or an extra bed.", "type": "string", "enum": [ "cot", "extra_bed" ] } } } }, "maximum_checkin_age": { "description": "Defines the maximum (inclusive) check-in age for this property. If null, then there is no maximum age for checking in", "type": "integer", "minimum": 18 }, "minimum_checkin_age": { "description": "Defines the minimum (inclusive) check-in age for this property.", "type": "integer", "minimum": 18 }, "minimum_guest_age": { "description": "Defines the minimum age (inclusive) for staying in this property. If \"0\", then a guest of any age is allowed.", "type": "integer", "minimum": 0 }, "pets": { "title": "AccommodationsPetsPolicyOutput", "type": "object", "properties": { "allowed": { "description": "An enumerated value describing if pets are allowed", "type": "string", "enum": [ "yes", "no", "upon_request" ] }, "charge_mode": { "description": "An enumerated value describing the charge mode for pets", "type": "string", "enum": [ "free", "charges_may_apply" ] } } }, "damage": { "type": "object", "description": "DamagePolicy of the property", "properties": { "deposit": { "description": "If a deposit needs to be paid upfront", "type": "object", "properties": { "collect": { "properties": { "date": { "type": "object", "properties": { "reference_date": { "type": "string", "enum": [ "checkin", "checkout" ] }, "days_offset": { "description": "The number of days on or before reference date.", "type": "integer" } } }, "payment_method": { "type": "string", "enum": [ "bank_transfer", "cash", "credit_card", "paypal", "other" ] } } }, "refund": { "properties": { "date": { "type": "object", "properties": { "reference_date": { "type": "string", "enum": [ "checkin", "checkout" ] }, "days_offset": { "description": "The number of days on or after reference date.", "type": "integer" } } }, "payment_method": { "type": "string", "enum": [ "bank_transfer", "cash", "credit_card", "paypal", "other" ] } } } } }, "amount": { "description": "The amount that can be charged", "type": "number", "format": "double" }, "currency": { "description": "Currency in which payment needs to be made", "type": "string" } } } } }, "price_category": { "description": "Indicates the qualitative price reference (between $ and $$$$) on how expensive an accommodation is. Accommodations in the same city are sorted by ascending price (average per guest per night in the last month), the ones in the lowest 25 percentile are in category $, between 25 and 50 percentile are in category $$, between 50 and 75 percentile are in category $$$, remaining ones are in category $$$$.", "type": "string", "pattern": "[$]{0,4}" }, "programmes": { "title": "AccommodationsProgrammes", "description": "Details of programmes undergone by the property.", "type": "object", "properties": { "travel_proud": { "description": "Boolean value is \"true\" if property has travel proud badge and \"false\" otherwise.", "type": "boolean" } } }, "ranking": { "description": "The public ranking of the accommodation.", "type": "number", "minimum": 0 }, "rating": { "title": "AccommodationsDetailsRatingOutput", "type": "object", "properties": { "number_of_reviews": { "description": "Number of validated reviews for this accommodation.", "type": "integer", "minimum": 0 }, "preferred": { "description": "Boolean value is \"true\" if this accommodation is in the Booking.com's preferred program and \"false\" otherwise.", "type": "boolean", "example": true }, "review_score": { "nullable": true, "description": "A decimal number indicating the current review score of this accommodation property, in the range 1..10.", "type": "number", "multipleOf": 0.1, "minimum": 1, "maximum": 10 }, "stars": { "description": "Number of stars of this accommodation property.", "type": "number", "format": "double", "multipleOf": 0.1, "nullable": true, "minimum": 1, "maximum": 5, "example": 4 }, "stars_type": { "description": "An enumerated value describing which type of stars this accommodation has.", "type": "string", "nullable": true, "enum": [ "estimated_by_accommodation", "estimated_by_booking", "official" ] } } }, "rooms": { "description": "The list of room types available at this property. Requires `{\"extras\":[\"rooms\"]}`.", "type": "array", "items": { "title": "AccommodationsDetailsRoomOutput", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property room. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "attributes": { "description": "Lists a set of attribute qualifiers for this room. Will not be returned if no relevant attributes are applicable.", "type": "array", "items": { "type": "string", "enum": [ "non_smoking", "smoking", "work_friendly" ] } }, "bed_options": { "description": "Lists all possible bedding options for this room or apartment.", "type": "array", "items": { "title": "AccommodationsBedOptionOutput", "description": "List of all possible bed arrangements. For apartments and other types of hotel accommodations, beds and bathrooms may be available as separate rooms.", "type": "object", "properties": { "bed_configurations": { "description": "Lists all alternative bed configurations that are supported.", "type": "array", "items": { "title": "AccommodationsBedConfigurationOutput", "description": "List of all beds available for this configuration.", "type": "object", "properties": { "id": { "description": "Uniquely identifies this bed configuration.", "type": "string" }, "configuration": { "description": "Detail list of all different types and number of beds included in this configuration.", "type": "array", "items": { "title": "AccommodationsBedOutput", "description": "Detail information about a type of bed and number of beds included in this configuration.", "type": "object", "properties": { "bed_type": { "description": "A signed integer number that uniquely identifies a bed type. Examples of bed types are: Single, Double etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 }, "number_of_beds": { "description": "Number of similar beds included in this configuration.", "type": "integer", "minimum": 0 } } } } } } }, "has_bathroom": { "description": "Flags if this area includes its own bathroom.", "type": "boolean" }, "is_bedroom": { "description": "Flags if this area is marked as a bedroom, otherwise, it should be considered a living room.", "type": "boolean" } } } }, "cots_and_extra_beds": { "title": "AccommodationsRoomsCotsAndExtraBedsOutput", "description": "Lists room options regarding adding cots and/or extra beds.", "type": "object", "properties": { "are_allowed_together": { "description": "Flags if cots and extra beds can be placed together in the room. `true` allows both up to their maximum limits. `false` requires exclusive choice of either cots or extra beds.", "type": "boolean" }, "maximum_number_of_cots": { "description": "Maximum number of cots that can be added.", "type": "integer", "minimum": 0 }, "maximum_number_of_extra_beds": { "description": "Maximum number of extra beds that can be added.", "type": "integer", "minimum": 0 } } }, "cribs_and_extra_beds": { "title": "AccommodationsRoomsCribsAndExtraBedsOutput", "description": "**DEPRECATED**, please use 'cots_and_extra_beds'.", "type": "object", "properties": { "are_allowed": { "description": "Flags if it's possible to add cribs and/or extra beds.", "type": "boolean" }, "maximum_number_of_cribs": { "description": "Maximum number of cribs that can be added.", "type": "integer", "minimum": 0 }, "maximum_number_of_extra_beds": { "description": "Maximum number of extra beds that can be added.", "type": "integer", "minimum": 0 } }, "deprecated": true }, "description": { "description": "Translated description of this room. The maximum number of characters returned may be limited by contract.", "title": "TranslatedString", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "facilities": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation property room facility. Examples of facilities are: Coffee/Tea maker, TV, Airconditioning, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 } }, "maximum_occupancy": { "title": "AccommodationsDetailsMaximumOccupancyOutput", "description": "Occupancy limits and options.", "type": "object", "properties": { "adults": { "description": "Maximum number of adults allowed.", "type": "integer", "minimum": 0 }, "children": { "description": "Maximum number of children allowed (children will be typically defined by being under 18 years of age).", "type": "integer", "minimum": 0 }, "total_guests": { "description": "**DEPRECATED** Total capacity of adults + children allowed.", "type": "integer", "minimum": 0, "deprecated": true } } }, "name": { "description": "Translated name of this room.", "title": "TranslatedString", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "number_of_rooms": { "title": "AccommodationsNumberOfRoomsOutput", "description": "Total rooms available.", "type": "object", "properties": { "bathrooms": { "description": "Total number of bathrooms.", "type": "integer", "minimum": 0 }, "bedrooms": { "description": "Total number of rooms equipped or that can be fitted with a bed.", "type": "integer", "minimum": 0 }, "living_rooms": { "description": "Total number of rooms without a bed.", "type": "integer", "minimum": 0 } } }, "photos": { "description": "List of photos for this accommodation room. The maximum number of photos returned may be limited by contract. Requires `{\"extras\":[\"rooms\",\"photos\"]}`. The photos are returned in no particular order.", "type": "array", "items": { "title": "AccommodationsPhotoOutput", "type": "object", "properties": { "main_photo": { "description": "Flags this as the main photo. Not returned otherwise.", "type": "boolean", "example": true }, "tags": { "type": "array", "items": { "description": "A list of tags associated with the photo. Manually generated.", "type": "string", "example": "Bathroom" } }, "url": { "title": "AccommodationsPhotoUrlOutput", "type": "object", "properties": { "large": { "description": "URL of the photo image with a maximum width of 1280 pixels.", "type": "string", "format": "url", "example": "https://q-xx.bstatic.com/xdata/images/hotel/max1280/20934654.jpg?k=806399263699a47361bdbbefc9c872a3db03eea26c4a815f5f4df95c93e38cdb&o=" }, "standard": { "description": "URL of the photo image with a maximum width of 500 pixels.", "type": "string", "format": "url", "example": "https://q-xx.bstatic.com/xdata/images/hotel/max500/20934654.jpg?k=806399263699a47361bdbbefc9c872a3db03eea26c4a815f5f4df95c93e38cdb&o=" }, "thumbnail": { "description": "URL of the photo thumbnail image with dimensions 100x100 pixels.", "type": "string", "format": "url", "example": "https://q-xx.bstatic.com/xdata/images/hotel/100x100/20934654.jpg?k=806399263699a47361bdbbefc9c872a3db03eea26c4a815f5f4df95c93e38cdb&o=" }, "thumbnail_large": { "description": "URL of the photo thumbnail image with dimensions 300x300 pixels.", "type": "string", "format": "url", "example": "https://q-xx.bstatic.com/xdata/images/hotel/300x300/20934654.jpg?k=806399263699a47361bdbbefc9c872a3db03eea26c4a815f5f4df95c93e38cdb&o=" } } } } } }, "room_type": { "description": "A signed integer number that uniquely identifies an accommodation property room type. Example of room types are: Suite, Apartment, Twin/Double etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 }, "size": { "description": "The room area in square meters.", "type": "number", "minimum": 0, "example": 20 } } } }, "spoken_languages": { "description": "Languages spoken by the staff of this accommodation property.", "type": "array", "items": { "description": "A [IETF language tag code](https://en.wikipedia.org/wiki/IETF_language_tag) that uniquely identifies a supported human language or dialect. **Note:** Demand API only accepts lowercase for the language codes. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" } }, "themes": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation property theme. Examples of themes are: Beach/Seaside, Ski/Wintersports, Luxury etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 1 } }, "url": { "description": "Internet address for the property page on Booking.com.", "type": "string", "format": "url" }, "work_friendly_home": { "description": "Whether the accommodation is work friendly. Applicable only for homes.", "type": "boolean" } } } }, "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`).", "type": [ "string", "null" ] } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 10004, "accommodation_type": 204, "brands": [], "bundles": [ { "id": 12345, "value_adds": [ { "type": "high_speed_internet", "description": { "en-gb": [ "High speed internet throughout your stay." ] } } ] } ], "checkin_checkout_times": { "checkin_from": "15:00:00", "checkin_to": null, "checkout_from": "07:00:00", "checkout_to": "12:00:00" }, "currency": "EUR", "deep_link_url": "booking://hotel/10004?affiliate_id=!AFFILIATE_ID!", "description": { "important_information": { "en-gb": "The credit card that has been used to book a non-refundable rate, will be charged on the day of booking and needs to be presented upon check-in. In case the credit card owner is not traveling with you, an online payment link will be sent to prepay your stay.\n\nPlease note that the hotel pre-authorizes your credit card with the amount for the first night, 8 days prior to arrival. This is not a payment and this only applies to flexible rates.\n\nParking in Amsterdam is challenging, there are parking garages near to the hotel or a valet service is possible to arrange upon request. Charges are applicable. Please contact the hotel ahead of time for information", "zh-cn": "酒店将在预订当天收取用于支付不退款房价的信用卡，客人需在办理入住手续时出示该信用卡。如果信用卡持有人未与客人同行，酒店将发送在线付款链接以预付客人的住宿费用。\n\n请注意，酒店将在客人抵达前8天通过其信用卡预授权第一晚的房费。这不是付款，这仅适用于变化的利率。\n\n在阿姆斯特丹（Amsterdam）停车很有挑战性，酒店附近有停车库，或者可应要求为客人安排代客泊车服务，收费适用。请提前联系酒店以获取信息。", "fallback": null }, "license_numbers": [], "text": { "en-gb": "The Pavilions Amsterdam, The Toren features elegant accommodation alongside the famous Keizersgracht canal, around the corner from the Anne Frank House. It offers elegant rooms with flat-screen TVs with digital entertainment system.\n\nEach air-conditioned room at the Toren has an en suite bathroom with a bathtub. They have classic decorations such as chandeliers and ceiling paintings. Tea/coffee making facilities and a complimentary mini bar are also provided in every room.\n\nIn the morning, guests can enjoy a delightful breakfast buffet in the elegant breakfast room with views of the Keizersgracht. The trendy hotel bar serves refreshing drinks during the day.\n\nWestermarkt Tram Stop is less than 250 metres from the hotel. Dam Square and the Royal Palace are a 10-minute walk away.", "zh-cn": "The Pavilions Amsterdam, The Toren酒店位于安妮弗兰克之家（Anne Frank House）拐角处，毗邻著名的Keizersgracht运河，提供典雅的住宿。酒店提供带平板电视和数字娱乐系统的典雅客房。\n\nToren酒店的每间空调客房均配有带浴缸的独立浴室。客房拥有典雅的装饰，如吊灯和天花板画。每间客房还提供沏茶/咖啡设施和免费迷你吧。\n\n早晨，客人可在典雅的早餐室享用可口的自助早餐，并欣赏Keizersgracht的景色。时髦的酒店酒吧白天提供清凉饮料。\n\n酒店距离韦斯特马克特电车站（Westermarkt Tram Stop）不到250米，距离水坝广场（Dam Square）和皇宫（Royal Palace）有10分钟的步行路程。", "fallback": null }, "trader": { "address": { "address_line": "Prinsengract 153", "city": "Amsterdam", "country": "nl", "post_code": "94571" }, "email": "test@test.test", "name": "Test Test", "registration_number": "123456788", "telephone": "+123456789", "trade_register": "hjdfvhfjd", "trader_verified": true } }, "facilities": [ { "id": 5, "attributes": [] }, "..." ], "is_genius": true, "is_work_friendly": false, "location": { "address": { "fallback": "Keizersgracht 164" }, "city": -2140479, "coordinates": { "latitude": 52.375858, "longitude": 4.886006 }, "country": "nl", "districts": [ 145, 3024, 9173 ], "postal_code": "1015 CZ", "regions": [ 1010, 2776 ] }, "long_stay_friendly_home": false, "meal_prices": { "breakfast": 20, "dinner": null, "lunch": null }, "name": { "fallback": "The Pavilions Amsterdam, The Toren" }, "number_of_rooms": 11, "payment": { "amex_cvc_required": false, "cvc_required": true, "domestic_no_cc": false, "methods": { "cash": true, "cards": [ 1, 2, 3 ], "virtual_cards": [ 1, 2, 3 ] }, "timings": [ "pay_at_the_property" ] }, "photos": [ { "main_photo": true, "tags": [ "Neighbourhood" ], "url": { "large": "https://q-xx.bstatic.com/xdata/images/hotel/max1280/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o=", "standard": "https://q-xx.bstatic.com/xdata/images/hotel/max500/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o=", "thumbnail": "https://q-xx.bstatic.com/xdata/images/hotel/100x100/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o=", "thumbnail_large": "https://q-xx.bstatic.com/xdata/images/hotel/300x300/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o=" } }, "..." ], "policies": { "cots_and_extra_beds": [ { "age": { "from": 0, "to": 2 }, "mode": "per_night", "price": 0, "type": "crib" } ], "damage": { "amount": 50, "currency": "EUR", "deposit": { "collect": { "date": { "days_offset": 0, "reference_date": "checkin" }, "payment_method": "credit_card" }, "refund": { "date": { "days_offset": 0, "reference_date": "checkout" }, "payment_method": "credit_card" } } }, "maximum_checkin_age": null, "minimum_checkin_age": 18, "minimum_guest_age": 0, "pets": { "allowed": "no", "charge_mode": null } }, "price_category": "$$$$", "programmes": { "travel_proud": false }, "ranking": 123456, "rating": { "number_of_reviews": 930, "preferred": true, "review_score": 9, "stars": 4, "stars_type": "official" }, "rooms": [ { "id": 1000420, "attributes": [ "non_smoking" ], "bed_options": [ { "bed_configurations": [ { "id": "1000420-1", "configuration": [ { "bed_type": 6, "number_of_beds": 1 } ] }, { "id": "1000420-2", "configuration": [ { "bed_type": 1, "number_of_beds": 2 } ] } ], "has_bathroom": true, "is_bedroom": true } ], "cots_and_extra_beds": { "are_allowed_together": false, "maximum_number_of_cots": 0, "maximum_number_of_extra_beds": 0 }, "cribs_and_extra_beds": { "are_allowed": false, "maximum_number_of_cribs": 0, "maximum_number_of_extra_beds": 0 }, "description": { "en-gb": "This room features decor with rich colours and original features. It is located in the annex building, 8 houses away from the main building. It is internally positioned, overlooking a small courtyard.", "fallback": null }, "facilities": [ 1, "..." ], "maximum_occupancy": { "adults": 2, "children": 1, "total_guests": 2 }, "name": { "en-gb": "Standard Double or Twin Room", "zh-cn": "标准双人或双床间 ", "fallback": null }, "number_of_rooms": { "bathrooms": 1, "bedrooms": 1, "living_rooms": 0 }, "photos": [ { "tags": [ "Neighbourhood" ], "url": { "large": "https://q-xx.bstatic.com/xdata/images/hotel/max1280/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o=", "standard": "https://q-xx.bstatic.com/xdata/images/hotel/max500/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o=", "thumbnail": "https://q-xx.bstatic.com/xdata/images/hotel/100x100/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o=", "thumbnail_large": "https://q-xx.bstatic.com/xdata/images/hotel/300x300/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o=" } }, "..." ], "room_type": 9, "size": 18 }, "..." ], "spoken_languages": [ "de", "en-gb", "fr", "nl" ], "themes": [ 6, "..." ], "url": "https://www.booking.com/hotel/nl/toren.html?affiliate_id=!AFFILIATE_ID!", "work_friendly_home": false } ] } } } } } } }, "/accommodations/details/changes": { "post": { "summary": "Updated accommodations", "description": "Use this endpoint to track accommodations that have opened, closed, or had relevant content updates since a specific timestamp. Changes can include updates to general information, facilities, rooms, photos, payments, and more.
You can:
- Filter results by country or city.
- Use the \"next\" timestamp from the response to request further updates.

To keep your local accommodation cache up to date, use this endpoint in combination with [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details)

The maximum number of IDs returned is approximately 5000 per request.", "operationId": "/accommodations/details/changes", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Accommodations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "AccommodationsDetailsChangesInput", "type": "object", "properties": { "last_change": { "description": "The timestamp in ISO-8601 format from which changes to accommodations are returned (inclusive). Only UTC time zone is supported. We support changes for last 24 hours. Format: YYYY-MM-DDTHH:mm:ss+00:00", "type": "string", "format": "date-time" }, "filters": { "description": "parameter basis which filtering needs to be done. Only one of (countries or cities) must be provided.", "type": "object", "properties": { "countries": { "description": "Filter changes based on these countries. The valid full list can be obtained by calling common/locations/countries.", "type": "array", "items": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" } }, "cities": { "description": "Filter changes based on these cities. The valid full list can be obtained by calling common/locations/cities.", "type": "array", "items": { "description": "A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.", "type": "integer" } } } } }, "required": [ "last_change" ] }, "example": { "last_change": "!START_DATE!T12:00:00+00:00", "filters": { "countries": [ "nl", "es", "in" ] } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "AccommodationsDetailsChangesOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "title": "AccommodationDetailsChangesDataOutput", "type": "object", "properties": { "changes": { "title": "AccommodationsDetailsChangesListOutput", "description": "The list of changed accommodations.", "type": "object", "properties": { "changed": { "type": "array", "items": { "description": "Accommodations which have had relevant changes to their content since the given timestamp. Changes being tracked include: general information, standard phrase, photos, payments, facilities and rooms.", "type": "integer" } }, "closed": { "type": "array", "items": { "description": "Accommodations which have closed since the given timestamp. Note that these same accommodations may be re-opened shortly after.", "type": "integer" } }, "opened": { "type": "array", "items": { "description": "Accommodations which have opened since the given timestamp. Note that sometimes accommodations may be closed again shortly after.", "type": "integer" } } } }, "from": { "description": "ISO 8601 timestamp which indicates the timestamp from which the changes are returned (inclusive).", "type": "string", "format": "date-time" }, "next": { "description": "ISO 8601 timestamp which indicates the next timestamp to be used for `last_change`. This will be 1 second after the latest change returned in the result (all changes from the \"last\" second are returned). NOTE: this field will not be present unless changes are returned. In this case, repeat the call after one minute with the same `last_change` date.", "type": "string", "format": "date-time" }, "total_changes": { "description": "Total number of changed accommodation ids returned. If 0, then repeat the call after one minute with the same `last_change` date.", "type": "integer" } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": { "changes": { "changed": [ 403115, "..." ], "closed": [ 9876832, "..." ], "opened": [ 8034270, "..." ] }, "from": "!START_DATE!T12:00:00+00:00", "next": "!START_DATE!T12:24:42+00:00", "total_changes": 5125 } } } } } } } }, "/accommodations/reviews": { "post": { "summary": "Accommodation reviews", "description": "This endpoint provides access to reviews for specified accommodations, allowing you to retrieve traveller feedback associated with a particular property.

✅ The reviews returned can be [filtered and sorted](/demand/docs/accommodations/filter-sorting), with the option to limit the number of reviews per accommodation by specifying the `rows` parameter.

Please note that the ratings **score is based on all traveller traffic across Booking.com**, and may not necessarily reflect the experience of your own customers.

If you choose to display or use these ratings and reviews, you are responsible for ensuring that your travellers are properly informed about what these scores represent.", "operationId": "/accommodations/reviews", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Accommodations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "AccommodationsReviewsInput", "type": "object", "properties": { "accommodations": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "maxItems": 100 }, "languages": { "description": "Limits reviews to those written in this language.", "type": "array", "items": { "description": "An IETF language tag code that uniquely identifies a supported human language or dialect as described here: https://en.wikipedia.org/wiki/IETF_language_tag. Note that in v3 the whole tag is always lowercase. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" } }, "last_change": { "description": "Limits the reviews to those changed after the given date. Format: YYYY-MM-DD.", "type": "string", "format": "date" }, "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" }, "reviewer": { "title": "AccommodationsReviewer", "type": "object", "properties": { "countries": { "description": "Limits reviews to those written by reviewer from the given country.", "type": "array", "items": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" } }, "travel_purposes": { "description": "Limits reviews to those written by specific travel purposes.", "type": "array", "items": { "description": "Defines if this was a leisure or business trip.", "type": "string", "enum": [ "business", "leisure" ] } }, "types": { "description": "Limits reviews to those written by specific reviewer type.", "type": "array", "items": { "description": "The reviewer type.", "type": "string", "enum": [ "couple", "extended_group", "family_with_children", "solo_traveller" ] } } } }, "rows": { "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "maximum": 100, "default": 100 }, "score": { "title": "AccommodationsReviewScoreInput", "type": "object", "properties": { "maximum": { "description": "Limits the reviews to those having score lesser or equal to this value.", "type": "integer", "minimum": 1, "maximum": 10 }, "minimum": { "description": "Limits the reviews to those having score greater or equal to this value.", "type": "integer", "minimum": 1, "maximum": 10 } } } }, "required": [ "accommodations" ] }, "example": { "accommodations": [ 10004 ], "languages": [ "en-gb" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "AccommodationsReviewsOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "AccommodationsReviewsDataOutput", "description": "", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "reviews": { "type": "array", "items": { "title": "AccommodationsReviewOutput", "type": "object", "properties": { "id": { "description": "Unique identifier of the review.", "type": "integer" }, "date": { "description": "The date when the review was last modified. Format: YYYY-MM-DD.", "type": "string", "format": "date" }, "language": { "description": "An IETF language tag code that uniquely identifies a supported human language or dialect as described here: https://en.wikipedia.org/wiki/IETF_language_tag. Note that in v3 the whole tag is always lowercase. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "negative": { "description": "Negative comments from this review.", "type": [ "string", "null" ] }, "positive": { "description": "Positive comments from this review.", "type": [ "string", "null" ] }, "reviewer": { "title": "AccommodationsReviewerOutput", "type": "object", "properties": { "country": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "name": { "description": "Name of the reviewer. If the value is null then the reviewer is anonymous.", "type": [ "string", "null" ] }, "travel_purpose": { "description": "Defines if this was a leisure or business trip.", "type": "string", "enum": [ "business", "leisure" ] }, "type": { "description": "The reviewer type.", "type": "string", "enum": [ "couple", "extended_group", "family_with_children", "solo_traveller" ] } } }, "score": { "description": "The aggregated score of the review.", "type": "number", "multipleOf": 0.1, "minimum": 1, "maximum": 10 }, "summary": { "description": "The summary of the review.", "type": [ "string", "null" ] }, "text_meets_guidelines": { "description": "Set to true when review meets the guidelines. The review text will be removed if it doesn't meet guidelines.", "type": "boolean" } } } }, "url": { "description": "Internet address for the property page on Booking.com.", "type": "string", "format": "url" } } } }, "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`).", "type": [ "string", "null" ] } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 10004, "reviews": [ { "id": 2130645894, "date": "2023-04-12", "language": "en-gb", "negative": "front entrance is not clean (\nbreakfast was served not like a buffet, every time you have to ask a waiter to bring additional food.", "positive": "beautiful hôtel in the central area", "reviewer": { "country": "ch", "name": "Svetlana", "travel_purpose": "leisure", "type": "couple" }, "score": 9, "summary": "Fantastic hotel with kind personal who are providing hospitality and excellent service.", "text_meets_guidelines": true }, "..." ], "url": "https://www.booking.com/hotel/nl/toren.html?aid=!AFFILIATE_ID!#tab-reviews" } ], "next_page": "..." } } } } } } }, "/accommodations/reviews/scores": { "post": { "summary": "Accommodation review scores", "description": "This endpoint returns score distribution and score breakdown for the specified accommodations. The scores information can be filtered by reviewer parameters and languages.", "operationId": "/accommodations/reviews/scores", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Accommodations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "AccommodationsReviewsInput", "type": "object", "properties": { "accommodations": { "type": "array", "items": { "description": "A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "maxItems": 100 }, "languages": { "description": "Limits reviews to those written in this language.", "type": "array", "items": { "description": "An IETF language tag code that uniquely identifies a supported human language or dialect as described here: https://en.wikipedia.org/wiki/IETF_language_tag. Note that in v3 the whole tag is always lowercase. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" } }, "reviewer": { "title": "AccommodationsReviewer", "type": "object", "properties": { "countries": { "description": "Limits reviews to those written by reviewer from the given country.", "type": "array", "items": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" } }, "travel_purposes": { "description": "Limits reviews to those written by specific travel purposes.", "type": "array", "items": { "description": "Defines if this was a leisure or business trip.", "type": "string", "enum": [ "business", "leisure" ] } }, "types": { "description": "Limits reviews to those written by specific reviewer type.", "type": "array", "items": { "description": "The reviewer type.", "type": "string", "enum": [ "couple", "extended_group", "family_with_children", "solo_traveller" ] } } } } }, "required": [ "accommodations" ] }, "example": { "accommodations": [ 10004 ], "languages": [ "en-gb" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "AccommodationsReviewsOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "AccommodationsReviewsScoresOutput", "description": "", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "breakdown": { "title": "AccommodationsReviewsBreakdownOutput", "description": "Review scores breakdown for each criteria. List of criteria includes: cleanliness, comfort, facilities, free_wifi, location, staff, value_for_money.", "type": "object", "patternProperties": { "^(cleanliness|comfort|facilities|free_wifi|location|staff|value_for_money)$": { "title": "AccommodationsReviewsBreakdownSchemaOutput", "type": "object", "properties": { "number_of_reviews": { "description": "Number of reviews for this criteria.", "type": "integer", "minimum": 0 }, "score": { "description": "A decimal number indicating the review score of this criteria, in the range 1..10.", "type": "number", "multipleOf": 0.1, "minimum": 1, "maximum": 10 } } } } }, "distribution": { "title": "AccommodationsReviewsDistributionOutput", "description": "Overall score distribution for each score (1-10).", "type": "object", "patternProperties": { "^[1-9]|10$": { "title": "AccommodationsReviewsDistributionSchemaOutput", "type": "object", "properties": { "number_of_reviews": { "description": "Number of reviews with this score.", "type": "integer", "minimum": 0 }, "percentage": { "description": "Percent of score distribution for this score.", "type": "number", "multipleOf": 0.01 } } } } }, "number_of_reviews": { "description": "Number of validated reviews for this accommodation.", "type": "integer", "minimum": 0 }, "score": { "description": "A decimal number indicating the current review score of this accommodation property, in the range 1..10.", "type": "number", "multipleOf": 0.1, "minimum": 1, "maximum": 10 }, "url": { "description": "Internet address for the property page on Booking.com.", "type": "string", "format": "url" } } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 10004, "breakdown": { "cleanliness": { "number_of_reviews": 243, "score": 9.27 }, "comfort": { "number_of_reviews": 242, "score": 9.26 }, "facilities": { "number_of_reviews": 242, "score": 8.84 }, "free_wifi": { "number_of_reviews": 24, "score": 8.75 }, "location": { "number_of_reviews": 242, "score": 9.59 }, "staff": { "number_of_reviews": 243, "score": 9.63 }, "value_for_money": { "number_of_reviews": 243, "score": 8.25 } }, "distribution": { "1": { "number_of_reviews": 1, "percentage": 0.41 }, "2": { "number_of_reviews": 0, "percentage": 0 }, "3": { "number_of_reviews": 2, "percentage": 0.82 }, "4": { "number_of_reviews": 2, "percentage": 0.82 }, "5": { "number_of_reviews": 5, "percentage": 2.06 }, "6": { "number_of_reviews": 3, "percentage": 1.23 }, "7": { "number_of_reviews": 18, "percentage": 7.41 }, "8": { "number_of_reviews": 41, "percentage": 16.87 }, "9": { "number_of_reviews": 67, "percentage": 27.57 }, "10": { "number_of_reviews": 104, "percentage": 42.8 } }, "number_of_reviews": 243, "score": 8.9, "url": "https://www.booking.com/hotel/nl/toren.html?aid=!AFFILIATE_ID!#tab-reviews" } ] } } } } } } }, "/common/languages": { "post": { "summary": "Retrieve language codes", "description": "This endpoint returns a list of human language codes and their names in the corresponding language. To get the full list call the endpoint passing an empty body. The language codes returned are what is used as input and output for other endpoints.", "operationId": "/common/languages", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Common/languages" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "LanguagesOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "LanguageOutput", "description": "The language code and its designation in the corresponding language.", "type": "object", "properties": { "id": { "description": "An IETF language tag code that uniquely identifies a supported human language or dialect as described here: https://en.wikipedia.org/wiki/IETF_language_tag. Note that in v3 the whole tag is always lowercase. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "name": { "type": "string" } } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": "ar", "name": "العربية" }, "..." ] } } } } } } }, "/common/locations/airports": { "post": { "summary": "Airports", "description": "This endpoint returns a list of airport codes and their names in the selected languages. The airports returned may be filtered by a location id. For example, you can get the list of airports in The Netherlands by passing: `{\"country\":\"nl\"}`. To get the full list call the endpoint passing an empty body. The airport codes returned are what is used as input and output for other endpoints. This endpoint implements pagination of the results.", "operationId": "/common/locations/airports", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Common/locations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "AirportsInput", "type": "object", "properties": { "airport": { "description": "A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling common/locations/airports.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "AMS" }, "city": { "description": "A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.", "type": "integer" }, "country": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "district": { "description": "A signed integer number that uniquely identifies a district. Typically, districts define known areas within a city. The full list can be obtained by calling common/locations/districts.", "type": "integer", "minimum": 1 }, "landmark": { "description": "A signed integer number that uniquely identifies a relevant geographical landmark, like a monument or a natural attraction. The full list can be obtained by calling common/locations/landmarks.", "type": "integer", "minimum": 1 }, "languages": { "type": "array", "items": { "description": "An IETF language tag code that uniquely identifies a supported human language or dialect as described here: https://en.wikipedia.org/wiki/IETF_language_tag. Note that in v3 the whole tag is always lowercase. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "default": [ "en-gb" ] }, "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" }, "region": { "description": "A signed integer number that uniquely identifies a geographical region. Regions usually define official administrative areas within a country, but may also include multiple countries and in some cases un-official but popular designations for geographical areas. An example of a region that crosses multiple countries is the Alps in Europe. The full list can be obtained by calling common/locations/regions.", "type": "integer", "minimum": 1 }, "rows": { "maximum": 1000, "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "default": 100 } } }, "example": { "country": "nl", "languages": [ "en-gb", "zh-cn" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "AirportsOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "AirportOutput", "description": "The three-letter IATA airport code and the translated name(s).", "type": "object", "properties": { "id": { "description": "A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling common/locations/airports.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "AMS" }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } } }, "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`). - string - 'null'" } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": "AMS", "name": { "en-gb": "Schiphol Airport", "zh-cn": "史基浦机场" } }, "..." ], "next_page": null } } } } } } }, "/common/locations/cities": { "post": { "summary": "Cities", "description": "This endpoint returns a list of city codes and their names in the selected languages. The cities returned may be filtered by a location id. For example, you can get the list of cities in The Netherlands by passing: `{\"country\":\"nl\"}`. To get the full list call the endpoint passing an empty body. The city codes returned are what is used as input and output for other endpoints. This endpoint implements pagination of the results.", "operationId": "/common/locations/cities", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Common/locations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "CitiesInput", "type": "object", "properties": { "airport": { "description": "A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling common/locations/airports.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "AMS" }, "city": { "description": "A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.", "type": "integer" }, "country": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "district": { "description": "A signed integer number that uniquely identifies a district. Typically, districts define known areas within a city. The full list can be obtained by calling common/locations/districts.", "type": "integer", "minimum": 1 }, "landmark": { "description": "A signed integer number that uniquely identifies a relevant geographical landmark, like a monument or a natural attraction. The full list can be obtained by calling common/locations/landmarks.", "type": "integer", "minimum": 1 }, "languages": { "type": "array", "items": { "description": "An IETF language tag code that uniquely identifies a supported human language or dialect as described here: https://en.wikipedia.org/wiki/IETF_language_tag. Note that in v3 the whole tag is always lowercase. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "default": [ "en-gb" ] }, "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" }, "region": { "description": "A signed integer number that uniquely identifies a geographical region. Regions usually define official administrative areas within a country, but may also include multiple countries and in some cases un-official but popular designations for geographical areas. An example of a region that crosses multiple countries is the Alps in Europe. The full list can be obtained by calling common/locations/regions.", "type": "integer", "minimum": 1 }, "rows": { "maximum": 1000, "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "default": 100 } } }, "example": { "country": "nl", "languages": [ "en-gb", "zh-cn" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "CitiesOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "CityOutput", "description": "The city internal code and the translated name(s).", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.", "type": "integer" }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "coordinates": { "title": "Coordinates", "type": "object", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } } } } } }, "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`).", "type": [ "string", "null" ] } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": -2156821, "name": { "zh-cn": "兹沃勒" }, "coordinates": { "latitude": 52.378281, "longitude": 4.90007 } }, "..." ], "next_page": "..." } } } } } } }, "/common/locations/countries": { "post": { "summary": "Countries", "description": "This endpoint returns a list of country codes and their names in the selected languages. The countries returned may be filtered by a location id. For example, you can get the list of countries that are associated with the European Alps region by passing: `{\"region\":1199}`.

To get the full list call the endpoint passing an empty body. The returned country codes are used as input and output for other endpoints.

This endpoint implements pagination of the results.", "operationId": "/common/locations/countries", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Common/locations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "CountriesInput", "type": "object", "properties": { "airport": { "description": "A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling common/locations/airports.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "AMS" }, "city": { "description": "A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.", "type": "integer" }, "country": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "district": { "description": "A signed integer number that uniquely identifies a district. Typically, districts define known areas within a city. The full list can be obtained by calling common/locations/districts.", "type": "integer", "minimum": 1 }, "landmark": { "description": "A signed integer number that uniquely identifies a relevant geographical landmark, like a monument or a natural attraction. The full list can be obtained by calling common/locations/landmarks.", "type": "integer", "minimum": 1 }, "languages": { "type": "array", "items": { "description": "An IETF language tag code that uniquely identifies a supported human language or dialect as described here: https://en.wikipedia.org/wiki/IETF_language_tag. Note that in v3 the whole tag is always lowercase. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "default": [ "en-gb" ] }, "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" }, "region": { "description": "A signed integer number that uniquely identifies a geographical region. Regions usually define official administrative areas within a country, but may also include multiple countries and in some cases un-official but popular designations for geographical areas. An example of a region that crosses multiple countries is the Alps in Europe. The full list can be obtained by calling common/locations/regions.", "type": "integer", "minimum": 1 }, "rows": { "maximum": 1000, "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "default": 100 } } }, "example": { "languages": [ "en-gb", "zh-cn" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "CountriesOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "CountryOutput", "description": "The two-letter ISO2 country code and the translated name(s).", "type": "object", "properties": { "id": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } } }, "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`).", "type": [ "string", "null" ] } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": "ad", "name": { "en-gb": "Andorra", "zh-cn": "安道尔" } }, "..." ], "next_page": "..." } } } } } } }, "/common/locations/districts": { "post": { "summary": "Districts", "description": "This endpoint returns a list of districts with translations in the selected languages. The districts returned may be filtered by a location id. For example, you can get the list of districts in Amsterdam by passing: `{\"city\":-2140479}`.

To get the full list call the endpoint passing an empty body. The district ids returned are what is used as input and output for other endpoints.

This endpoint implements pagination of the results.", "operationId": "/common/locations/districts", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Common/locations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "DistrictsInput", "type": "object", "properties": { "airport": { "description": "A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling common/locations/airports.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "AMS" }, "city": { "description": "A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.", "type": "integer" }, "country": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "district": { "description": "A signed integer number that uniquely identifies a district. Typically, districts define known areas within a city. The full list can be obtained by calling common/locations/districts.", "type": "integer", "minimum": 1 }, "landmark": { "description": "A signed integer number that uniquely identifies a relevant geographical landmark, like a monument or a natural attraction. The full list can be obtained by calling common/locations/landmarks.", "type": "integer", "minimum": 1 }, "languages": { "type": "array", "items": { "description": "An IETF language tag code that uniquely identifies a supported human language or dialect as described here: https://en.wikipedia.org/wiki/IETF_language_tag. Note that in v3 the whole tag is always lowercase. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "default": [ "en-gb" ] }, "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" }, "region": { "description": "A signed integer number that uniquely identifies a geographical region. Regions usually define official administrative areas within a country, but may also include multiple countries and in some cases un-official but popular designations for geographical areas. An example of a region that crosses multiple countries is the Alps in Europe. The full list can be obtained by calling common/locations/regions.", "type": "integer", "minimum": 1 }, "rows": { "maximum": 1000, "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "default": 100 } } }, "example": { "city": -2140479, "languages": [ "en-gb", "zh-cn" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "DistrictsOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "DistrictOutput", "description": "The district id and the translated name(s).", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies a district. Typically, districts define known areas within a city. The full list can be obtained by calling common/locations/districts.", "type": "integer", "minimum": 1 }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "coordinates": { "title": "Coordinates", "type": "object", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } } } } } }, "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`).", "type": [ "string", "null" ] } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 145, "name": { "en-gb": "Amsterdam City Centre", "zh-cn": "阿姆斯特丹市中心" }, "coordinates": { "latitude": 52.378281, "longitude": 4.90007 } }, "..." ], "next_page": null } } } } } } }, "/common/locations/landmarks": { "post": { "summary": "Landmarks", "description": "This endpoint returns a list of relevant geographical landmark codes and their names in the selected languages. The landmarks returned may be filtered by a location id. For example, you can get the list of landmarks that are associated with the city of Paris in France by passing: `{\"city\":-1456928}`.

To get the full list call the endpoint passing an empty body. The landmark codes returned are what is used as input and output for other endpoints.

This endpoint implements pagination of the results.", "operationId": "/common/locations/landmarks", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Common/locations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "LandmarksInput", "type": "object", "properties": { "airport": { "description": "A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling common/locations/airports.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "AMS" }, "city": { "description": "A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.", "type": "integer" }, "country": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "district": { "description": "A signed integer number that uniquely identifies a district. Typically, districts define known areas within a city. The full list can be obtained by calling common/locations/districts.", "type": "integer", "minimum": 1 }, "landmark": { "description": "A signed integer number that uniquely identifies a relevant geographical landmark, like a monument or a natural attraction. The full list can be obtained by calling common/locations/landmarks.", "type": "integer", "minimum": 1 }, "languages": { "type": "array", "items": { "description": "An IETF language tag code that uniquely identifies a supported human language or dialect as described here: https://en.wikipedia.org/wiki/IETF_language_tag. Note that in v3 the whole tag is always lowercase. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "default": [ "en-gb" ] }, "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" }, "region": { "description": "A signed integer number that uniquely identifies a geographical region. Regions usually define official administrative areas within a country, but may also include multiple countries and in some cases un-official but popular designations for geographical areas. An example of a region that crosses multiple countries is the Alps in Europe. The full list can be obtained by calling common/locations/regions.", "type": "integer", "minimum": 1 }, "rows": { "maximum": 1000, "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "default": 100 } } }, "example": { "city": -2140479, "languages": [ "en-gb", "zh-cn" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "LandmarksOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "LandmarkOutput", "description": "The landmark internal code and the translated name(s).", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies a relevant geographical landmark, like a monument or a natural attraction. The full list can be obtained by calling common/locations/landmarks.", "type": "integer", "minimum": 1 }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "coordinates": { "title": "Coordinates", "type": "object", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } } } } } }, "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`).", "type": [ "string", "null" ] } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 1, "coordinates": { "latitude": 52.378281, "longitude": 4.90007 }, "name": { "en-gb": "Amsterdam Central Station", "zh-cn": "阿姆斯特丹中央车站" } }, "..." ], "next_page": "..." } } } } } } }, "/common/locations/regions": { "post": { "summary": "Regions", "description": "This endpoint returns a list of regions with translations in the selected languages. The regions returned may be filtered by a location id. For example, you can get the list of regions in the Netherlands or that the Netherlands is a part of by passing: `{\"country\":\"nl\"}`. To get the full list call the endpoint passing an empty body. The region ids returned are what is used as input and output for other endpoints. This endpoint implements pagination of the results.", "operationId": "/common/locations/regions", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Common/locations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "RegionsInput", "type": "object", "properties": { "airport": { "description": "A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling common/locations/airports.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "AMS" }, "city": { "description": "A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.", "type": "integer" }, "country": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "landmark": { "description": "A signed integer number that uniquely identifies a relevant geographical landmark, like a monument or a natural attraction. The full list can be obtained by calling common/locations/landmarks.", "type": "integer", "minimum": 1 }, "languages": { "type": "array", "items": { "description": "An IETF language tag code that uniquely identifies a supported human language or dialect as described here: https://en.wikipedia.org/wiki/IETF_language_tag. Note that in v3 the whole tag is always lowercase. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "default": [ "en-gb" ] }, "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" }, "region": { "description": "A signed integer number that uniquely identifies a geographical region. Regions usually define official administrative areas within a country, but may also include multiple countries and in some cases un-official but popular designations for geographical areas. An example of a region that crosses multiple countries is the Alps in Europe. The full list can be obtained by calling common/locations/regions.", "type": "integer", "minimum": 1 }, "rows": { "maximum": 1000, "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "default": 100 } } }, "example": { "country": "nl", "languages": [ "en-gb", "zh-cn" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "RegionsOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "RegionOutput", "description": "The region id and the translated name(s).", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies a geographical region. Regions usually define official administrative areas within a country, but may also include multiple countries and in some cases un-official but popular designations for geographical areas. An example of a region that crosses multiple countries is the Alps in Europe. The full list can be obtained by calling common/locations/regions.", "type": "integer", "minimum": 1 }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } } }, "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`).", "type": [ "string", "null" ] } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 1003, "name": { "en-gb": "Drenthe", "zh-cn": "德伦特省" } }, "..." ], "next_page": null } } } } } } }, "/common/payments/cards": { "post": { "summary": "Payment cards", "description": "This endpoint returns a list of supported payment cards and their names in English. Examples of payment types are the different credit and debit cards.

To get the full list call the endpoint passing an empty body. The codes returned are what is used as input and output for other endpoints.", "operationId": "/common/payments/cards", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Common/payments" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "CardsDataOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "PaymentCardOutput", "description": "The payment card identifier code and its designation in English.", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies a payment type. Examples of payment types are the different credit and debit cards. The full list can be obtained by calling common/payments/cards.", "type": "integer", "minimum": 1 }, "name": { "type": "string" } } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 1, "name": "American Express" }, "..." ] } } } } } } }, "/common/payments/currencies": { "post": { "summary": "Currencies", "description": "This endpoint returns a list of currency codes and their names in the selected languages. To get the full list call the endpoint passing an empty body.

The currency codes returned are what is used as input and output for other endpoints.", "operationId": "/common/payments/currencies", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Common/payments" ], "requestBody": { "content": { "application/json": { "schema": { "title": "CurrenciesInput", "type": "object", "properties": { "languages": { "type": "array", "items": { "description": "A [IETF language tag code](https://en.wikipedia.org/wiki/IETF_language_tag) that uniquely identifies a supported human language or dialect. **Note:** Demand API only accepts lowercase for the language codes. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "default": [ "en-gb" ] } } }, "example": { "languages": [ "en-gb", "zh-cn" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "CurrenciesOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "CurrencyOutput", "description": "The ISO 4217 currency code and its designation in the selected language.", "type": "object", "properties": { "id": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": "AED", "name": { "en-gb": "U.A.E. dirham", "zh-cn": "阿联酋迪拉姆" } }, "..." ] } } } } } } }, "/orders/preview": { "post": { "summary": "Preview an order", "description": "This endpoint returns the total final price with final charges, as well as the price breakdown and payment/cancellation policies for each product passed in the input.", "operationId": "/orders/preview", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Orders" ], "requestBody": { "content": { "application/json": { "schema": { "title": "OrdersPreviewInput", "type": "object", "properties": { "booker": { "title": "OrdersPreviewBookerOutput", "description": "The booker's information.", "type": "object", "properties": { "country": { "description": "The booker country for showing the best price for that user and obeying laws regarding the display of taxes and fees.", "type": "string", "pattern": "^[a-z]{2}$" }, "platform": { "description": "The booker platform for showing the platform based deals and prices.", "type": "string", "enum": [ "android", "desktop", "ios", "mobile", "tablet" ] }, "travel_purpose": { "description": "The travel purpose of the booker.", "type": "string", "enum": [ "business", "leisure" ] }, "user_groups": { "description": "The user groups that the booker is a member of.", "type": "array", "items": { "type": "string", "enum": [ "authenticated" ] } } }, "required": [ "country", "platform" ] }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "accommodation": { "title": "OrdersPreviewAccommodationInput", "description": "Input parameter with the checkin and checkout date and all the accommodation products to be ordered.", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "checkin": { "description": "The checkin date. Must be within 500 days in the future and in the format yyyy-mm-dd.", "type": "string", "format": "date" }, "checkout": { "description": "The checkout date. Must be later than {checkin}. Must be between 1 and 90 days after {checkin}. Must be within 500 days in the future and in the format yyyy-mm-dd.", "type": "string", "format": "date" }, "products": { "type": "array", "items": { "title": "OrdersPreviewProductInput", "description": "Input parameter with the product id and the desired allocation for that product", "type": "object", "properties": { "id": { "description": "Unique ID of the product.", "type": "string" }, "allocation": { "title": "OrdersPreviewAccommodationAllocationOutput", "description": "The exact allocation of guests to a room.", "type": "object", "properties": { "children": { "description": "The children ages for this room.", "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17 } }, "number_of_adults": { "description": "The number of adults for this room.", "type": "integer", "minimum": 1 } }, "required": [ "number_of_adults" ] } } } } } } }, "required": [ "booker", "accommodation" ] }, "example": { "booker": { "country": "nl", "platform": "mobile", "travel_purpose": "leisure", "user_groups": [ "authenticated" ] }, "currency": "EUR", "accommodation": { "id": 6745031, "checkin": "!START_DATE!", "checkout": "!END_DATE!", "products": [ { "id": "674503106_275710478_0_2_0", "allocation": { "number_of_adults": 1, "children": [ 8 ] } }, { "id": "674503113_275710486_0_1_0", "allocation": { "number_of_adults": 1, "children": [] } } ] } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "OrdersPreviewOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "title": "OrdersPreviewDataOutput", "description": "", "type": "object", "properties": { "accommodation": { "title": "OrdersPreviewAccommodationOutput", "description": "The products to order related to an accommodation", "type": "object", "properties": { "id": { "description": "A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).", "type": "integer", "minimum": 1 }, "currency": { "title": "OrdersPreviewCurrencyOutput", "type": "object", "properties": { "accommodation": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "booker": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" } } }, "general_policies": { "properties": { "payment": { "title": "AccommodationsProductPaymentTimingsDates", "description": "", "type": "object", "properties": { "pay_online_now": { "title": "AccommodationsPayOnlineNow", "type": [ "object", "null" ], "properties": { "dates": { "description": "Schedule specifying the instalments for paying the order for the \"pay_online_now\" option. For each,entry in the schedule, a charge will be made at the time of that entry.", "type": "array", "items": { "title": "AccommodationsPaymentSchedule", "type": "object", "properties": { "at": { "description": "The date at which this instalment will be charged.", "type": "string", "format": "date" }, "price": { "description": "The amount charged in this instalment.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } } }, "method_required": { "description": "Whether a payment method is required for this payment timing.", "type": "boolean" }, "methods": { "title": "AccommodationsPaymentMethods", "type": "object", "description": "The payment methods available for the payment timing selected.", "properties": { "airplus": { "description": "Whether airplus can be used as a payment method for this order.", "type": "boolean" }, "cards": { "description": "The cards available to pay.", "type": "array", "items": { "description": "A signed integer number that uniquely identifies a payment type. Examples of payment types are the different credit and debit cards. The full list can be obtained by calling common/payments/cards.", "type": "integer", "minimum": 1 } }, "wallet": { "description": "Whether wallet can be used as a payment method for this order.", "type": "boolean" } }, "nullable": true } } }, "pay_online_later": { "title": "AccommodationsPayOnlineLater", "type": "object", "properties": { "dates": { "description": "Schedule specifying the instalments for paying the order for this product for the \"pay_online_later\" option. For each entry in the schedule, a charge will be made at the time of that entry.", "type": "array", "items": { "title": "AccommodationsPaymentSchedule", "type": "object", "properties": { "at": { "description": "The date at which this instalment will be charged.", "type": "string", "format": "date" }, "price": { "description": "The amount charged in this instalment.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } } }, "method_required": { "description": "Whether a payment method is required for this payment timing.", "type": "boolean" }, "methods": { "title": "AccommodationsPaymentMethods", "type": "object", "description": "The payment methods available for the payment timing selected.", "properties": { "airplus": { "description": "Whether airplus can be used as a payment method for this order.", "type": "boolean" }, "cards": { "description": "The cards available to pay.", "type": "array", "items": { "description": "A signed integer number that uniquely identifies a payment type. Examples of payment types are the different credit and debit cards. The full list can be obtained by calling common/payments/cards.", "type": "integer", "minimum": 1 } }, "wallet": { "description": "Whether wallet can be used as a payment method for this order.", "type": "boolean" } }, "nullable": true } }, "nullable": true }, "pay_at_the_property": { "title": "AccommodationsPayAtTheProperty", "type": "object", "properties": { "dates": { "description": "Schedule specifying the instalments for paying the order for this product for the \"pay_at_the_property\" option. For each entry in the schedule, a charge will be made at the time of that entry.", "type": "array", "items": { "title": "AccommodationsPaymentSchedule", "type": "object", "properties": { "at": { "description": "The date at which this instalment will be charged.", "type": "string", "format": "date" }, "price": { "description": "The amount charged in this instalment.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } } }, "method_required": { "description": "Whether a payment method is required for this payment timing.", "type": "boolean" }, "methods": { "title": "AccommodationsPaymentMethods", "type": "object", "description": "The payment methods available for the payment timing selected.", "properties": { "airplus": { "description": "Whether airplus can be used as a payment method for this order.", "type": "boolean" }, "cards": { "description": "The cards available to pay.", "type": "array", "items": { "description": "A signed integer number that uniquely identifies a payment type. Examples of payment types are the different credit and debit cards. The full list can be obtained by calling common/payments/cards.", "type": "integer", "minimum": 1 } }, "wallet": { "description": "Whether wallet can be used as a payment method for this order.", "type": "boolean" } }, "nullable": true } }, "nullable": true } } } } }, "price": { "title": "OrdersPreviewProductSumPriceOutput", "description": "The price components of all the products selected summed", "type": "object", "properties": { "base": { "description": "The sum base price of all products selected. Does not include any extra charges.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "chargeable_online": { "description": "The price that will be charged by Booking.com when online payments are used. This field does not apply to the \"pay_at_the_property\" timing.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "total": { "description": "The total sum price. Includes all extra charges of all products.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "extra_charges": { "description": "The sum of charges for all products selected, grouped by charge type.", "conditional": { "description": "The sum of conditional charges for all products selected, grouped by charge type.", "type": "array", "items": { "$ref": "../accommodations/dataTypes.json#/conditionalChargeMultiCurrencySummary" } }, "non_conditional": { "description": "The sum of non-conditional charges for all products selected, grouped by charge type.", "type": "array", "items": { "$ref": "../accommodations/dataTypes.json#/conditionalChargeMultiCurrencySummary" } } } } }, "products": { "type": "array", "items": { "title": "OrdersPreviewProductOutput", "description": "The returned information of the product selected", "type": "object", "properties": { "id": { "description": "Unique ID of the product.", "type": "string" }, "bundle": { "description": "The bundle ID of the product comprising of value added products.", "type": "integer" }, "deal": { "title": "Deal", "description": "This specifies the deal tagging for the product.", "type": [ "object", "null" ], "properties": { "discount_percentage": { "description": "Discount percentage of the applied deal.", "type": "integer", "minimum": 1 }, "public_price": { "description": "Original price of this product, before applying any discounts.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "tags": { "description": "The tags of all the applied deals.", "type": "array", "items": { "type": "string", "enum": [ "black_friday", "limited_time_deal", "logged_in_deal", "mobile_rate", "seasonal_deal" ] } } } }, "inventory": { "title": "InventoryOutput", "type": "object", "properties": { "third_party": { "type": "boolean", "description": "Boolean value is \"true\" if the product is facilitated by a Booking.com partner company and \"false\" otherwise." }, "type": { "description": "Type of inventory - either net or sell rates.", "type": "string", "enum": [ "net", "sell" ] } } }, "policies": { "title": "AccommodationsProductDetailedPoliciesMultiCurrency", "description": "The policies for this product.", "type": "object", "properties": { "cancellation": { "description": "The cancellation policy schedule for this product.", "type": "array", "items": { "title": "AccommodationsProductDetailedCancellationPolicyMultiCurrency", "type": "object", "properties": { "from": { "description": "The time from which this cancellation fee applies. `now` means from booking time.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "now" }, { "type": "null" } ] }, "price": { "description": "The cancellation fee.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } } }, "meal_plan": { "title": "AccommodationsProductMealPlanPolicy", "description": "The meal plan policy for this product.", "type": "object", "properties": { "meals": { "description": "The meals included in the meal plan.", "type": "array", "items": { "type": "string", "enum": [ "breakfast", "dinner", "lunch" ] } }, "plan": { "description": "The meal plan included in this product.", "type": "string", "enum": [ "all_inclusive", "breakfast_included", "full_board", "half_board", "no_plan" ] } } } } }, "price": { "title": "OrdersPreviewProductPriceOutput", "description": "The price components of this product. 'base' and 'extra_charges' are returned only when explicitly requested (via 'extras=extra_charges').", "type": "object", "properties": { "base": { "description": "The base price. It does not include any extra charges.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "chargeable_online": { "description": "The price that will be charged by Booking.com when online payments are used. This field does not apply to the \"pay_at_the_property\" timing.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "extra_charges": { "title": "OrdersPreviewProductExtraChargesOutput", "description": "The charge breakdown. Includes taxes and fees.", "type": "object", "properties": { "conditional": { "description": "Charges that might apply under a specific condition.", "type": "array", "items": { "title": "AccommodationsConditionalChargeMultiCurrency", "description": "Charges that might apply under a specific condition.", "type": "object", "properties": { "charge": { "description": "A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 0 }, "condition": { "description": "A signed integer number that uniquely identifies the condition ID. Find the full list in the Pricing guidelines.", "type": [ "integer", "null" ], "minimum": 0 }, "mode": { "description": "The mode of this charge. Determines how the price is calculated.", "type": "string", "enum": [ "calculated_amount", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay" ] }, "percentage": { "description": "The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "total_amount": { "description": "The total price for this charge.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "unit_amount": { "description": "The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.", "nullable": true, "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } } }, "non_conditional": { "description": "All non-conditional charges that will necessarily be paid", "type": "array", "items": { "title": "AccommodationsChargeMultiCurrency", "description": "All non-conditional charges that will necessarily be paid", "type": "object", "properties": { "charge": { "description": "A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 0 }, "chargeable_online": { "description": "Whether this charge is chargeable online or not. Not applicable to \"pay_at_the_property\" timing.", "type": "boolean" }, "mode": { "description": "The mode of this charge. Determines how the price is calculated.", "type": "string", "enum": [ "calculated_amount", "incalculable", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay" ] }, "percentage": { "description": "The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "total_amount": { "description": "The total price for this charge.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "unit_amount": { "description": "The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.", "nullable": true, "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } } } } }, "total": { "description": "The total price. Includes all extra charges.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } }, "room": { "description": "A signed long number that uniquely identifies an accommodation property room. The full list can be obtained by calling [accommodations/details](#/accommodations/details).", "type": "number", "minimum": 1, "nullable": true }, "third_party_inventory": { "description": "Boolean value is \"true\" if the product is facilitated by a Booking.com partner company and \"false\" otherwise.", "type": "boolean" } } } } } }, "order_token": { "description": "A token containing the necessary data to be used on subsequent requests to [orders/create].", "type": "string" } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": { "accommodation": { "id": 6745031, "currency": { "accommodation": "EUR", "booker": null }, "general_policies": { "payment": { "pay_online_now": { "dates": [ { "at": "!TODAY!", "price": { "accommodation_currency": 177.65, "booker_currency": null } } ], "method_required": false, "methods": { "airplus": true, "cards": [ 1, 2, 3 ], "wallet": true } }, "pay_online_later": { "dates": [ { "at": "!TODAY!", "price": { "accommodation_currency": 0, "booker_currency": null } }, { "at": "!START_DATE-2!", "price": { "accommodation_currency": 177.65, "booker_currency": null } }, { "at": "!START_DATE!", "price": { "accommodation_currency": 0, "booker_currency": null } } ], "method_required": false, "methods": { "airplus": true, "cards": [ 1, 2, 3, 5 ], "wallet": true } }, "pay_at_the_property": { "dates": [ { "at": "!TODAY!", "price": { "accommodation_currency": 0, "booker_currency": null } }, { "at": "!START_DATE!", "price": { "accommodation_currency": 177.65, "booker_currency": null } } ], "method_required": true, "methods": { "airplus": true, "cards": [ 1, 2 ], "wallet": false } } } }, "price": { "base": { "accommodation_currency": 100, "booker_currency": null }, "chargeable_online": { "accommodation_currency": 100, "booker_currency": null }, "total": { "accommodation_currency": 123, "booker_currency": null }, "extra_charges": { "conditional": [], "non_conditional": [ { "charge": 142, "chargeable_online": true, "total_amount": { "accommodation_currency": 6, "booker_currency": null } }, { "charge": 21, "chargeable_online": false, "total_amount": { "accommodation_currency": 14.67, "booker_currency": null } }, { "charge": 22, "chargeable_online": true, "total_amount": { "accommodation_currency": 11.41, "booker_currency": null } } ] } }, "products": [ { "id": "1000420_278556531_2_0_0", "bundle": null, "deal": null, "inventory": { "third_party": false, "type": "sell" }, "policies": { "cancellation": [ { "from": "now", "price": { "accommodation_currency": 0, "booker_currency": null } }, { "from": "!START_DATE-2!T22:00:00+00:00", "price": { "accommodation_currency": 177.65, "booker_currency": null } } ], "meal_plan": { "meals": [], "plan": "no_plan" } }, "price": { "base": { "accommodation_currency": 155.96, "booker_currency": null }, "chargeable_online": { "accommodation_currency": 186.92, "booker_currency": null }, "extra_charges": { "conditional": [], "non_conditional": [ { "charge": 142, "chargeable_online": true, "mode": "per_person_per_night", "percentage": null, "total_amount": { "accommodation_currency": 6, "booker_currency": null }, "unit_amount": 3 }, { "charge": 21, "chargeable_online": false, "mode": "percentage", "percentage": 9, "total_amount": { "accommodation_currency": 14.04, "booker_currency": null }, "unit_amount": null }, { "charge": 22, "chargeable_online": true, "mode": "percentage", "percentage": 7, "total_amount": { "accommodation_currency": 10.92, "booker_currency": null }, "unit_amount": null } ] }, "total": { "accommodation_currency": 186.92, "booker_currency": null } }, "third_party_inventory": false }, { "id": "tpi-1000420_95127794_2_0_0", "deal": null, "inventory": { "third_party": true, "type": "sell" }, "policies": { "cancellation": [ { "from": "now", "price": { "accommodation_currency": 170, "booker_currency": null } } ], "meal_plan": { "meals": [], "plan": "no_plan" } }, "price": { "base": { "accommodation_currency": 162.98, "booker_currency": null }, "extra_charges": { "conditional": [ { "charge": 3, "condition": 30, "mode": "per_stay", "percentage": null, "total_amount": { "accommodation_currency": 10, "booker_currency": null }, "unit_amount": null } ], "non_conditional": [ { "charge": 142, "mode": "per_person_per_night", "percentage": null, "total_amount": { "accommodation_currency": 6, "booker_currency": null }, "unit_amount": { "accommodation_currency": 3, "booker_currency": null } }, { "charge": 21, "mode": "percentage", "percentage": 9, "total_amount": { "accommodation_currency": 14.67, "booker_currency": null }, "unit_amount": null }, { "charge": 22, "mode": "percentage", "percentage": 7, "total_amount": { "accommodation_currency": 11.41, "booker_currency": null }, "unit_amount": null } ] }, "total": { "accommodation_currency": 195.06, "booker_currency": null } }, "third_party_inventory": true } ] }, "order_token": "..." } } } } } } } }, "/orders/create": { "post": { "summary": "Create an order", "description": "Use this endpoint to confirm the booking and proceed the payment.", "operationId": "/orders/create", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Orders" ], "requestBody": { "content": { "application/json": { "schema": { "title": "OrderCreateInput", "type": "object", "properties": { "accommodation": { "title": "OrderCreateAccommodationInput", "description": "Additional information related to the accommodation order.", "type": "object", "properties": { "label": { "description": "A label for this order. This can be read back later while fetching this order details.", "type": "string" }, "products": { "description": "", "type": "array", "items": { "title": "OrderCreateProductInformationInput", "description": "Additional information related to each product related to the products in this order.", "type": "object", "properties": { "id": { "description": "ID for this product. `Please note that this MUST match the product IDs used for related /orders/preview request.`", "type": "string" }, "bed_configuration": { "description": "Bed configuration ID to select for this product. `Please note that it can not be guaranteed that the selected bed_configuration will be available.`", "type": "string" }, "guests": { "description": "The guest details for this product.", "type": "array", "items": { "title": "OrderCreateGuestInput", "type": "object", "properties": { "email": { "description": "The email address of the guest.", "type": "string" }, "name": { "description": "The name of the guest.", "type": "string" } }, "required": [ "email", "name" ] } } }, "required": [ "id" ] } }, "remarks": { "title": "OrderCreateRemarksInput", "description": "Optional remarks from the guest.", "type": "object", "properties": { "estimated_arrival_time": { "title": "EstimatedArrivalTimeInput", "description": "Estimated arrival time of the guests.", "type": "object", "properties": { "hour": { "description": "Approximate hour of arrival to the hotel. Allowed values are from 0 to 23. This time should be within the hotel reception hours, or will be ignored otherwise with a warning will be appended to special_requests.", "type": "integer", "minimum": 0, "maximum": 23 }, "next_day": { "description": "Set this to true, if the hour selected is for the day after checkin.", "type": "boolean", "default": "false" } }, "required": [ "hour" ] }, "special_requests": { "description": "Optional comments or requests from the guest. Special requests cannot be guaranteed – but the property will do its best to meet your needs.", "type": "string" } } } } }, "booker": { "title": "OrderCreateBookerInput", "description": "The booker's information.", "type": "object", "properties": { "address": { "title": "OrderCreateAddressInput", "description": "The booker's address to be used for creating this order. All fields of this object are required if the /accommodations/details endpoint indicates that the booker's address is necessary by returning booker_address_required=true.", "type": "object", "properties": { "address_line": { "description": "The details of this address.", "type": "string" }, "city": { "description": "The city for this address.", "type": "string" }, "country": { "description": "The country for this address.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "post_code": { "description": "Post code for this address.", "type": "string" } }, "required": [ "country" ] }, "company": { "description": "The booker's company name.", "type": "string" }, "email": { "description": "The booker's email address.", "type": "string" }, "language": { "description": "A [IETF language tag code](https://en.wikipedia.org/wiki/IETF_language_tag) that uniquely identifies a supported human language or dialect. **Note:** Demand API only accepts lowercase for the language codes. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "name": { "title": "OrderCreateBookerNameInput", "description": "The name of the booker.", "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" } }, "required": [ "first_name", "last_name" ] }, "telephone": { "description": "The booker's telephone number.", "type": "string" } }, "required": [ "address", "email", "name", "telephone" ] }, "order_token": { "description": "A token containing the necessary data to be used for creating this order.", "type": "string" }, "payment": { "title": "OrderCreatePaymentInput", "description": "Payment related information for the order.", "type": "object", "properties": { "airplus": { "description": "All information related to airplus payment. `This is required if airplus is selected as payment method.`", "type": "object", "properties": { "dbi": { "title": "OrderCreateDbiInput", "description": "Descriptive billing information(dbi) details to pass to AirPlus.", "type": "object", "properties": { "accounting_code": { "description": "Accounting code to pass in descriptive billing information.", "type": "string", "minLength": 1, "maxLength": 17 }, "accounting_unit": { "description": "Accounting unit to pass in descriptive billing information.", "type": "string", "minLength": 1, "maxLength": 17 }, "cost_centre": { "description": "Cost centre to pass in descriptive billing information.", "type": "string", "minLength": 1, "maxLength": 17 }, "department_code": { "description": "Department code to pass in descriptive billing information.", "type": "string", "minLength": 1, "maxLength": 17 }, "employee_number": { "description": "Employee number to pass in descriptive billing information.", "type": "string", "minLength": 1, "maxLength": 17 }, "internal_account": { "description": "Internal account to pass in descriptive billing information.", "type": "string", "minLength": 1, "maxLength": 17 }, "order_number": { "description": "Order number to pass in descriptive billing information.", "type": "string", "minLength": 1, "maxLength": 17 }, "project_number": { "description": "Project number to pass in descriptive billing information.", "type": "string", "minLength": 1, "maxLength": 17 } } }, "number": { "description": "12 digit Airplus Number.", "type": "string" } }, "required": [ "number" ] }, "business_information": { "title": "OrderCreateBusinessInformationInput", "description": "All business related information for billing and authorisation form. This must be included for the payments that require authorisation form.", "type": "object", "properties": { "authorisation_form": { "title": "OrderCreateAuthorisationFormInput", "description": "Information that is relevant for generating an authorisation form.", "type": "object", "properties": { "chargeable_items": { "description": "Items which can be charged using a provided virtual credit card.", "type": "array", "items": { "type": "string", "enum": [ "alcohol", "breakfast", "food_beverage", "internet", "parking", "phone", "taxes" ] } } } }, "billing": { "title": "OrderCreateBillingInput", "description": "All information to be used in the invoice.", "type": "object", "properties": { "address": { "title": "OrderCreateBusinessAddressInput", "description": "The address to bill this reservation", "type": "object", "properties": { "address_line": { "description": "The details of this address.", "type": "string" }, "city": { "description": "The city for this address.", "type": "string" }, "country": { "description": "The country for this address.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "post_code": { "description": "Post code for this address.", "type": "string" } } }, "email": { "description": "Email to send the invoice to.", "type": "string" }, "vat": { "description": "VAT number to be used in the invoice.", "type": "string" } }, "required": [ "email", "vat" ] }, "company": { "description": "Company that will issue an authorisation form for the virtual credit card and used in the invoice.", "type": "string" } }, "required": [ "company" ] }, "card": { "title": "OrderCreateCardInput", "description": "Card information for executing the payment.", "type": "object", "properties": { "authentication": { "title": "OrderCreateCardAuthenticationInput", "description": "Card authentication information for executing the payment.", "type": "object", "properties": { "riskified": { "title": "OrderCreateRiskifiedInput", "description": "Riskified information for external fraud verification.", "type": "object", "properties": { "ip_address": { "description": "The booker's IP address.", "type": "string", "format": "ipv4" }, "session_id": { "description": "Riskified provided session_id for external fraud verification.", "type": "string" } }, "required": [ "ip_address", "session_id" ] }, "sca_exemption": { "description": "The type of SCA exemption to be applied to the payment.", "type": "string", "enum": [ "moto", "virtual" ] }, "3d_secure": { "title": "OrderCreate3dSecureInput", "description": "3-factor authentication information for the card.", "type": "object", "properties": { "authentication_value": { "description": "Cardholder Authentication Verification Value.", "type": "string" }, "cavv": { "deprecated": true, "description": "Deprecated. Do not use", "type": "string" }, "eci": { "description": "The electronic commerce indicator.", "type": "string" }, "transaction": { "description": "The unique ID assigned by the DS to identify a single transaction.", "type": "string" } }, "required": [ "authentication_value", "eci", "transaction" ] } } }, "cardholder": { "description": "Name of the cardholder.", "type": "string" }, "cvc": { "description": "3 or 4 digits card validation code (CVC) of this card.", "type": "string" }, "expiry_date": { "description": "Expiry date of the card. Format: YYYY-MM", "type": "string" }, "number": { "description": "Number of the card.", "type": "string" } }, "required": [ "cardholder", "cvc", "expiry_date", "number" ] }, "include_receipt": { "description": "This is used to determine whether to include payment `receipt_url` in the response or not.", "type": "boolean" }, "method": { "description": "The payment method to be used for this order.", "type": "string", "enum": [ "airplus", "card", "wallet" ] }, "timing": { "description": "Information about when to execute the payment.", "type": "string", "enum": [ "pay_at_the_property", "pay_online_later", "pay_online_now" ] } }, "required": [ "timing" ] } }, "required": [ "booker", "order_token", "payment" ] }, "example": { "accommodation": { "label": "Sample label", "products": [ { "id": "333", "bed_configuration": "123456", "guests": [ { "email": "test.name@booking.com", "name": "Test Name" } ] } ], "remarks": { "estimated_arrival_time": { "hour": 12 }, "special_requests": "We will need an extra cot." } }, "booker": { "address": { "address_line": "Road-1, house-2", "city": "Amsterdam", "country": "nl", "post_code": "11111" }, "company": "Booking B.V", "email": "test.name@booking.com", "language": "en-gb", "name": { "first_name": "Test", "last_name": "Name" }, "telephone": "12345678" }, "order_token": "sample-token", "payment": { "card": { "cardholder": "Test Name", "cvc": "111", "expiry_date": "2030-10", "number": "23333333333333" }, "include_receipt": true, "method": "card", "timing": "pay_at_the_property" } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "OrderCreateOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "title": "OrderCreateDataOutput", "type": "object", "properties": { "accommodation": { "title": "OrderCreateAccommodationOutput", "description": "All accommodation related information for this order.", "type": "object", "properties": { "order": { "description": "ID for this accommodation order.", "type": "string" }, "pincode": { "description": "Pincode for this accommodation order.", "type": "string" }, "reservation": { "description": "Reservation ID for this accommodation order.", "type": "integer", "format": "int64" }, "third_party_inventory": { "title": "Third party inventory related information for the created order. This field is only available for third party inventory orders.", "type": "object", "properties": { "checkin_number": { "description": "The number required at the time of check-in. It allows guests to confirm their order at the accommodation.", "type": "string", "example": "473026811" }, "confirmation_number": { "description": "The confirmation number, when used in conjunction with the pincode, helps verify the customer's order and facilitates efficient support during inquiries or troubleshooting.", "type": "string", "example": "12365478936925814787" } } } } }, "payment": { "title": "OrderCreatePaymentOutput", "description": "All payment related information for this order.", "type": "object", "properties": { "authorisation_form_url": { "description": "Link to a virtual credit card''s authorisation form, valid for 7 minutes from issue. `This will only the added if the request has authorisation_form.`", "type": "string", "format": "uri", "example": "https://secure-admin.booking.com/airplus_auth_form_pdf.html?token=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA&lang=en" }, "receipt_url": { "description": "Link to the payment receipt of the order. `This will only be added if include_receipt is true.`", "type": "string", "format": "uri", "example": "https://secure.booking.com/payment_receipt.html?bn=0000000000&pincode=0000&lang=en" } } } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": { "accommodation": { "order": "509430129718799", "pincode": "0000", "reservation": 12345678, "third_party_inventory": { "checkin_number": "123456789", "confirmation_number": "12345678912345678912" } }, "payment": { "receipt_url": "https://secure.booking.com/payment_receipt.html?bn=0000000000&pincode=0000&lang=en" } } } } } } } } }, "/orders/details": { "post": { "summary": "Orders details", "description": "This endpoint returns basic information for orders filtered according to the input.", "operationId": "/orders/details", "parameters": [ { "in": "header", "name": "X-Affiliate-Id", "schema": { "type": "integer" }, "required": true, "description": "Include here your Affiliate identifier number" } ], "tags": [ "Orders" ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "title": "InputByUpdated", "type": "object", "properties": { "updated": { "title": "OrderDetailsDatetimeFilterInput", "description": "Filtering orders by time range on basis of order \"created\" or \"updated\" time. Maximum time range is 7 days (1 week).", "type": "object", "properties": { "from": { "description": "ISO 8601 timestamp in UTC, which indicates the timestamp from which you want to filter orders from (inclusive). The value should be within last 1 year.", "type": "string", "format": "date-time" }, "to": { "description": "ISO 8601 timestamp in UTC, which indicates the timestamp till which you want to filter orders to (inclusive). It has to be greater than or equal to \"from\".", "type": "string", "format": "date-time" } }, "required": [ "from" ] }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "maximum_results": { "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "maximum": 100, "default": 100 }, "sort": { "title": "OrderDetailsSortInput", "description": "The sorting parameters for the response.", "type": "object", "properties": { "by": { "description": "The way to sort your results.", "type": "string", "enum": [ "created", "updated" ], "default": "created" }, "direction": { "description": "The direction you wish for your sort.by parameter to be sorted in.", "type": "string", "enum": [ "ascending", "descending" ], "default": "descending" } }, "required": [ "by", "direction" ] }, "extras": { "description": "Input parameter to request for additional information about this order.", "type": "array", "items": { "type": "string", "enum": [ "payment" ] } }, "services": { "description": "Filter orders by included services.", "type": "array", "items": { "type": "string", "enum": [ "accommodations", "cars", "flights" ] } } }, "required": [ "updated", "currency" ] }, { "title": "InputByCreated", "type": "object", "properties": { "created": { "title": "OrderDetailsDatetimeFilterInput", "description": "Filtering orders by time range on basis of order \"created\" or \"updated\" time. Maximum time range is 7 days (1 week).", "type": "object", "properties": { "from": { "description": "ISO 8601 timestamp in UTC, which indicates the timestamp from which you want to filter orders from (inclusive). The value should be within last 1 year.", "type": "string", "format": "date-time" }, "to": { "description": "ISO 8601 timestamp in UTC, which indicates the timestamp till which you want to filter orders to (inclusive). It has to be greater than or equal to \"from\".", "type": "string", "format": "date-time" } }, "required": [ "from" ] }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "maximum_results": { "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "maximum": 100, "default": 100 }, "sort": { "title": "OrderDetailsSortInput", "description": "The sorting parameters for the response.", "type": "object", "properties": { "by": { "description": "The way to sort your results.", "type": "string", "enum": [ "created", "updated" ], "default": "created" }, "direction": { "description": "The direction you wish for your sort.by parameter to be sorted in.", "type": "string", "enum": [ "ascending", "descending" ], "default": "descending" } }, "required": [ "by", "direction" ] }, "extras": { "description": "Input parameter to request for additional information about this order.", "type": "array", "items": { "type": "string", "enum": [ "payment" ] } }, "services": { "description": "Filter orders by included services.", "type": "array", "items": { "type": "string", "enum": [ "accommodations", "cars", "flights" ] } } }, "required": [ "created", "currency" ] }, { "title": "InputByStart", "type": "object", "properties": { "start": { "title": "OrderDetailsDateFilterInput", "description": "Filter orders by date range, covering the \"start\" and \"end\" date. The maximum date range is up to 7 days (1 week).", "type": "object", "properties": { "from": { "description": "ISO 8601 date in \"YYYY-MM-DD\" format. It indicates from which date you want to filter the orders. You can filter orders up to 1 year in the past and 500 days in the future.", "type": "string", "format": "date", "example": "2024-06-01" }, "to": { "description": "ISO 8601 date in \"YYYY-MM-DD\" format. It indicates until which date you want to filter the orders to (inclusive). It has to be greater than or equal to \"from\". It uses \"from\" value as default.", "type": "string", "format": "date", "example": "2024-06-03" } }, "required": [ "from" ] }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "maximum_results": { "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "maximum": 100, "default": 100 }, "sort": { "title": "OrderDetailsSortInput", "description": "The sorting parameters for the response.", "type": "object", "properties": { "by": { "description": "The way to sort your results.", "type": "string", "enum": [ "created", "updated" ], "default": "created" }, "direction": { "description": "The direction you wish for your sort.by parameter to be sorted in.", "type": "string", "enum": [ "ascending", "descending" ], "default": "descending" } }, "required": [ "by", "direction" ] }, "extras": { "description": "Input parameter to request for additional information about this order.", "type": "array", "items": { "type": "string", "enum": [ "payment" ] } }, "services": { "description": "Filter orders by included services.", "type": "array", "items": { "type": "string", "enum": [ "accommodations", "cars", "flights" ] } } }, "required": [ "start", "currency" ] }, { "title": "InputByEnd", "type": "object", "properties": { "end": { "title": "OrderDetailsDateFilterInput", "description": "Filter orders by date range, covering the \"start\" and \"end\" date. The maximum date range is up to 7 days (1 week).", "type": "object", "properties": { "from": { "description": "ISO 8601 date in \"YYYY-MM-DD\" format. It indicates from which date you want to filter the orders. You can filter orders up to 1 year in the past and 500 days in the future.", "type": "string", "format": "date", "example": "2024-06-01" }, "to": { "description": "ISO 8601 date in \"YYYY-MM-DD\" format. It indicates until which date you want to filter the orders to (inclusive). It has to be greater than or equal to \"from\". It uses \"from\" value as default.", "type": "string", "format": "date", "example": "2024-06-03" } }, "required": [ "from" ] }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "maximum_results": { "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "maximum": 100, "default": 100 }, "sort": { "title": "OrderDetailsSortInput", "description": "The sorting parameters for the response.", "type": "object", "properties": { "by": { "description": "The way to sort your results.", "type": "string", "enum": [ "created", "updated" ], "default": "created" }, "direction": { "description": "The direction you wish for your sort.by parameter to be sorted in.", "type": "string", "enum": [ "ascending", "descending" ], "default": "descending" } }, "required": [ "by", "direction" ] }, "extras": { "description": "Input parameter to request for additional information about this order.", "type": "array", "items": { "type": "string", "enum": [ "payment" ] } }, "services": { "description": "Filter orders by included services.", "type": "array", "items": { "type": "string", "enum": [ "accommodations", "cars", "flights" ] } } }, "required": [ "end", "currency" ] }, { "title": "InputByOrders", "type": "object", "properties": { "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "orders": { "description": "List of order IDs for which details should be returned.", "type": "array", "items": { "description": "Order ID for which details should be returned.", "type": "string" }, "maxItems": 100 }, "sort": { "title": "OrderDetailsSortInput", "description": "The sorting parameters for the response.", "type": "object", "properties": { "by": { "description": "The way to sort your results.", "type": "string", "enum": [ "created", "updated" ], "default": "created" }, "direction": { "description": "The direction you wish for your sort.by parameter to be sorted in.", "type": "string", "enum": [ "ascending", "descending" ], "default": "descending" } }, "required": [ "by", "direction" ] }, "extras": { "description": "Input parameter to request for additional information about this order.", "type": "array", "items": { "type": "string", "enum": [ "payment" ] } }, "services": { "description": "Filter orders by included services.", "type": "array", "items": { "type": "string", "enum": [ "accommodations", "cars", "flights" ] } } }, "required": [ "orders", "currency" ] }, { "title": "InputByReservations", "type": "object", "properties": { "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "reservations": { "description": "List of reservation IDs for which details should be returned.", "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "sort": { "title": "OrderDetailsSortInput", "description": "The sorting parameters for the response.", "type": "object", "properties": { "by": { "description": "The way to sort your results.", "type": "string", "enum": [ "created", "updated" ], "default": "created" }, "direction": { "description": "The direction you wish for your sort.by parameter to be sorted in.", "type": "string", "enum": [ "ascending", "descending" ], "default": "descending" } }, "required": [ "by", "direction" ] }, "extras": { "description": "Input parameter to request for additional information about this order.", "type": "array", "items": { "type": "string", "enum": [ "payment" ] } }, "services": { "description": "Filter orders by included services.", "type": "array", "items": { "type": "string", "enum": [ "accommodations", "cars", "flights" ] } } }, "required": [ "reservations", "currency" ] }, { "title": "InputByPage", "type": "object", "properties": { "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" }, "extras": { "description": "Input parameter to request for additional information about this order.", "type": "array", "items": { "type": "string", "enum": [ "payment" ] } } }, "required": [ "page" ] } ] }, "example": { "created": { "from": "2025-07-28T02:00:00+00:00", "to": "2025-07-28T02:00:00+00:00" }, "currency": "EUR", "maximum_results": 20, "sort": { "by": "updated", "direction": "descending" }, "extras": [ "payment" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "OrderDetailsOutput", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "OrderDetailsDataOutput", "description": "All details for this order.", "type": "object", "properties": { "id": { "description": "The id for this order.", "type": "string" }, "accommodations": { "title": "OrderDetailsAccommodationsOutput", "type": "object", "properties": { "inventory": { "title": "InventoryOutput", "type": "object", "properties": { "third_party": { "type": "boolean", "description": "Boolean value is \"true\" if the product is facilitated by a Booking.com partner company and \"false\" otherwise." }, "type": { "description": "Type of inventory - either net or sell rates.", "type": "string", "enum": [ "net", "sell" ] } } }, "reservation": { "description": "This is the reservation id for the accommodation in this order.", "type": "integer", "format": "int64" } } }, "affiliate": { "description": "The affiliate id used for this order.", "type": "integer" }, "booker": { "title": "OrderDetailsBookerOutput", "description": "The booker's information.", "type": "object", "properties": { "address": { "title": "OrderDetailsAddressOutput", "description": "The booker's address for showing the best price for that user and obeying laws regarding the display of taxes and fees.", "type": "object", "properties": { "city": { "description": "The city for this address.", "type": [ "string", "null" ] }, "country": { "description": "The country for this address.", "type": [ "string", "null" ] } } }, "email": { "description": "The booker's email address.", "type": [ "string", "null" ] }, "language": { "description": "A [IETF language tag code](https://en.wikipedia.org/wiki/IETF_language_tag) that uniquely identifies a supported human language or dialect. **Note:** Demand API only accepts lowercase for the language codes. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "name": { "title": "OrderDetailsBookerNameOutput", "description": "The name of the booker.", "type": "object", "properties": { "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] } } }, "platform": { "description": "The booker platform for showing the platform based deals and prices.", "type": "string", "enum": [ "app", "desktop", "mobile_browser", "tablet", "unknown" ] }, "telephone": { "description": "The booker's telephone number.", "type": "string", "nullable": true }, "travel_purpose": { "description": "The travel purpose of the booker.", "type": "string", "enum": [ "business", "leisure", "unknown" ] } } }, "cars": { "title": "OrderDetailsCarsOutput", "type": "object", "properties": { "reservation": { "description": "This is the reservation id for the car in this order.", "type": "integer", "format": "int64" } } }, "created": { "description": "Order creation time.", "type": "string", "format": "date-time" }, "commission": { "title": "OrderDetailsCommissionOutput", "description": "Commission details for the partner for a given order.", "type": "object", "properties": { "actual_amount": { "description": "For accommodation: This is the final commission for this order (`null` if value is not yet available). For other travel services: It represents the estimated commission before billing and the final commission after billing.", "nullable": true, "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "estimated_amount": { "description": "Estimated commission amount for this order. For accommodations, it will be `null` if the final commission amount is available.", "nullable": true, "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "currency": { "description": "Input currency used in \"commission\" and \"price\" output fields.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "flights": { "title": "OrderDetailsFlightsOutput", "type": "object", "properties": { "reservation": { "description": "This is the reservation id for flight in this order.", "type": "integer", "format": "int64" } } }, "loyalty_reward": { "nullable": true, "description": "Details of the loyalty rewards associated with this order.", "type": "array", "items": { "title": "OrderDetailsLoyaltyRewardOutput", "type": "object", "properties": { "amount": { "description": "Reward amount, in the units of the specified reward type (such as cash, mile, point, etc.).", "type": "number", "format": "double" }, "currency": { "description": "Currency used for reward calculation.", "nullable": true, "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "eligible": { "description": "Whether the order is eligible for the reward.", "type": "boolean" }, "fulfillment_at": { "description": "Date and time at which the reward should be fulfilled.", "type": "string", "format": "date" }, "fulfillment_by": { "description": "Mode of fulfillment of the reward.", "type": "string", "enum": [ "partner", "booking.com" ] }, "loyalty_data": { "description": "Loyalty data associated with this loyalty reward used to fulfill reward.", "type": "array", "items": { "title": "OrderDetailsLoyaltyDataOutput", "type": "object", "properties": { "name": { "description": "Name of the loyalty data.", "type": "string" }, "value": { "description": "Value of the loyalty data.", "type": "string" } } }, "nullable": true }, "type": { "description": "Type of reward.", "type": "string", "enum": [ "cash", "mile", "point", "voucher", "voucher_money", "voucher_subscription", "voucher_percentage" ] } } } }, "payment": { "title": "OrderDetailsPaymentOutput", "description": "The payment details of this order.", "type": "object", "properties": { "accommodations": { "title": "OrderDetailsAccommodationPaymentOutput", "description": "The accommodation specific payment details of this order.", "type": "object", "properties": { "authorisation_form": { "description": "Link to the authorisation form of the order.", "type": "string", "format": "uri", "example": "https://secure-admin.booking.com/airplus_auth_form_pdf.html?token=AAAA&lang=en-us", "nullable": true }, "receipt_url": { "description": "Link to the payment receipt of the order. `This will only be added if the payment is already charged.`", "type": "string", "format": "uri", "example": "https://secure.booking.com/payment_receipt.html?bn=0000000000&pincode=0000&lang=en", "nullable": true }, "reservation": { "description": "Reservation ID for this accommodation order.", "type": "integer", "format": "int64" } }, "nullable": true }, "method": { "description": "The payment method of this order.", "type": "string", "enum": [ "airplus", "card", "wallet" ] }, "paid": { "description": "The paid transactions for this order.", "nullable": true, "type": "array", "items": { "title": "OrderDetailsPaymentTransactionOutput", "type": "object", "properties": { "amount": { "description": "Amount of the transaction.", "type": "number" }, "at": { "description": "Time of the transaction.", "type": "string", "format": "date-time" }, "transaction_currency": { "description": "Currency in which the transaction took place.", "type": "string" } } } }, "pending": { "description": "The pending transactions for this order.", "nullable": true, "type": "array", "items": { "title": "OrderDetailsPaymentTransactionOutput", "type": "object", "properties": { "amount": { "description": "Amount of the transaction.", "type": "number" }, "at": { "description": "Time of the transaction.", "type": "string", "format": "date-time" }, "transaction_currency": { "description": "Currency in which the transaction took place.", "type": "string" } } } }, "timing": { "description": "The payment timing of this order.", "type": "string", "enum": [ "pay_at_the_property", "pay_online_later", "pay_online_now" ] } } }, "price": { "title": "OrderDetailsPriceOutput", "description": "The price components of this order.", "type": "object", "properties": { "commissionable": { "description": "The commissionable price. Order price on which commission amount is calculated.", "nullable": true, "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "total": { "description": "The total price. Includes all extra charges.", "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } }, "nullable": true }, "status": { "description": "Status of this order.", "type": "string", "enum": [ "booked", "cancelled", "cancelled_by_accommodation", "cancelled_by_guest", "no_show", "stayed" ] }, "updated": { "description": "Time the order was last updated.", "type": "string", "format": "date-time" } } } }, "metadata": { "title": "MetadataOutput", "description": "Metadata about the request.", "type": "object", "properties": { "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`).", "type": "string", "nullable": true }, "total_results": { "description": "The total number of results available.", "type": "integer", "minimum": 0 } } }, "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": "509430129718799", "accommodations": { "inventory": { "third_party": false, "type": "sell" }, "reservation": 12345677 }, "affiliate": 111111, "booker": { "address": { "city": "Amsterdam", "country": "nl" }, "email": "johndoe@booking.com", "language": "en-gb", "name": { "first_name": "john", "last_name": "doe" }, "platform": "mobile_browser", "telephone": "+100000000", "travel_purpose": "business" }, "commission": { "actual_amount": 17.5, "estimated_amount": null }, "created": "2025-07-28T02:00:00+00:00", "currency": "EUR", "flights": null, "loyalty_reward": [ { "amount": 15, "currency": "USD", "eligible": true, "fulfillment_at": "2025-02-10", "fulfillment_by": "partner", "loyalty_data": [ { "name": "Email Id", "value": "john_doe@booking.com" }, { "name": "Loyalty ID", "value": "10101010" } ], "type": "point" } ], "price": { "commissionable": 160, "total": 170.01 }, "status": "booked", "updated": "2025-07-28T02:00:00+00:00" } ], "metadata": { "next_page": null, "total_results": 1 } } } } } } } }, "/orders/details/accommodations": { "post": { "summary": "Orders with accommodation details", "description": "This endpoint returns all information for given accommodation orders, sorted by `bookingDate` in descending order", "operationId": "/orders/details/accommodations", "parameters": [ { "in": "header", "name": "X-Affiliate-Id", "schema": { "type": "integer" }, "required": true, "description": "Include here your Affiliate identifier number" } ], "tags": [ "Orders" ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "title": "AccommodationsDetailsInputByOrders", "type": "object", "properties": { "orders": { "description": "List of order IDs for which details should be returned.", "type": "array", "items": { "description": "Order ID for which details should be returned.", "type": "string" }, "maxItems": 100 }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "extras": { "description": "Input parameter to request for additional information about the accommodation order. It should be passed as a JSON array with one or more items.", "type": "array", "items": { "type": "string", "enum": [ "accommodation_details", "policies", "extra_charges" ] } }, "language": { "description": "Language in which translation should be provided. The default language is from settings", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" } }, "required": [ "orders" ] }, { "title": "AccommodationsDetailsInputByReservations", "type": "object", "properties": { "reservations": { "type": "array", "items": { "description": "Accommodation reservation id for which details have to be returned.", "type": "integer", "format": "int64" }, "maxItems": 100 }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "extras": { "description": "Input parameter to request for additional information about the accommodation order. It should be passed as a JSON array with one or more items.", "type": "array", "items": { "type": "string", "enum": [ "accommodation_details", "policies", "extra_charges" ] } }, "language": { "description": "Language in which translation should be provided. The default language is from settings", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" } }, "required": [ "reservations" ] } ] }, "example": { "currency": "USD", "extras": [ "policies", "extra_charges" ], "reservations": [ 2321873123, 4666773123 ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "OrdersDetailsAccommodationsOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "OrdersDetailsAccommodationsOutput", "description": "Object containing all the information related to accommodation order.", "type": "object", "properties": { "id": { "description": "Order ID for this accommodation order.", "type": "string" }, "accommodation": { "description": "Hotel ID for this accommodation order.", "type": "integer" }, "accommodation_details": { "title": "OrdersAccommodationDetailsOutput", "description": "Accommodation details for this accommodation order (via 'extras=accommodation_details').", "type": "object", "properties": { "email": { "description": "Accommodation email.", "type": "string" }, "location": { "title": "AccommodationLocationOutput", "description": "Accommodation location.", "type": "object", "properties": { "address": { "description": "Accommodation address.", "type": "string" }, "city": { "description": "Accommodation city_id.", "type": "number" }, "coordinates": { "title": "AccommodationCoordinatesOutput", "description": "Accommodation coordinates.", "type": "object", "properties": { "latitude": { "description": "Accommodation latitude coordinate.", "type": "number" }, "longitude": { "description": "Accommodation longitude coordinate.", "type": "number" } } }, "country": { "description": "Accommodation country.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "post_code": { "description": "Accommodation post code.", "type": "string" } } }, "name": { "description": "Accommodation name.", "type": "string" }, "telephone": { "description": "Accommodation telephone.", "type": "string" } } }, "accommodation_order_references": { "description": "List of additional accommodation order references generated by the accommodation.", "type": "array", "items": { "type": "string" } }, "booker": { "title": "OrderDetailsBookerOutput", "description": "The booker's information.", "type": "object", "properties": { "external_account": { "description": "This is a unique identifier that represents the account provided by the partner in Booking.com settings. This field is used to link a specific accommodation order to the corresponding account so is possible to accurately allocate loyalty points or other benefits in the partner's loyalty and rewards programs.", "type": "string" }, "platform": { "description": "The booker platform for showing the platform based deals and prices.", "type": "string", "enum": [ "app", "desktop", "mobile_browser", "tablet", "unknown" ] } } }, "cancellation_details": { "title": "OrderCancellationDetailsOutput", "description": "Fee charged for cancellation and the datetime at which the cancellation occurred. (If not cancelled, value is null).", "type": "object", "properties": { "at": { "description": "Cancellation datetime.", "type": "string", "format": "date-time" }, "fee": { "description": "Cancellation fee.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "original_total_price": { "description": "The total amount that would have been charged if this order had not been cancelled. Includes all extra charges.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } }, "nullable": true }, "checkin": { "description": "The checkin date of this accommodation order.", "type": "string", "format": "date" }, "checkout": { "description": "The checkout date of this accommodation order.", "type": "string", "format": "date" }, "commission": { "title": "OrderCommissionOutput", "description": "Commission details for the partner for this accommodation order.", "type": "object", "properties": { "actual_amount": { "description": "Actual commission amount for this accommodation order (`null` if value is not yet available).", "nullable": true, "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "actual_percentage": { "description": "Actual commission percentage for this accommodation order (`null` if value is not yet available).", "type": "number", "format": "double", "nullable": true }, "estimated_amount": { "description": "Estimated commission amount for this accommodation order (`null` if the actual amount is given).", "nullable": true, "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } }, "credit_slip": { "description": "**DEPRECATED**, please use 'credit_slip_number'.", "type": "integer", "format": "int64", "deprecated": true }, "credit_slip_number": { "description": "The financial document issued by Booking.com to partners, detailing the payout amount and the associated transaction information. It serves as a formal record of the payment, ensuring transparency and facilitating accurate financial tracking for both parties.", "type": "string", "nullable": true }, "currency": { "title": "OrderCurrencyOutput", "description": "Accommodation and booker currencies (booker will be `null`, if the request did not specify the currency).", "type": "object", "properties": { "accommodation": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "booker": { "nullable": true, "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" } } }, "inventory": { "title": "InventoryOutput", "type": "object", "properties": { "third_party": { "type": "boolean", "description": "Boolean value is \"true\" if the product is facilitated by a Booking.com partner company and \"false\" otherwise." }, "type": { "description": "Type of inventory - either net or sell rates.", "type": "string", "enum": [ "net", "sell" ] } } }, "key_collection_information": { "type": "array", "items": { "title": "AccommodationsKeyCollectionInformationOutput", "type": "object", "properties": { "additional_instructions": { "description": "Free-text instructions that provide additional context or details about the key collection or check-in process, such as access codes, entry procedures, or contact information.", "type": "string" }, "alternate_location": { "title": "AlternateLocationOutput", "description": "This is the alternate location where the key for this accommodation property can be collected. It is provided if the key is not available at the accommodation property itself but instead at another designated location.", "type": "object", "properties": { "address": { "type": "string" }, "city": { "type": "string" }, "postal_code": { "type": "string" } } }, "checkin_method": { "description": "An enumeration that describes the check-in process and key collection method. This is typically applicable to non-hotel accommodations (such as houses or apartments) that do not have a 24-hour front desk.", "type": "string", "enum": [ "door_code", "lock_box", "reception", "secret_spot", "someone_will_meet", "unknown" ] }, "key_location": { "description": "Location of the key to access this accommodation property.", "type": "string", "enum": [ "key_location_at_the_property", "key_location_different_place", "unknown" ] } } } }, "label": { "description": "The label created while booking given accommodation order.", "type": "string", "nullable": true }, "pin_code": { "description": "The pin code of this accommodation order.", "type": "string" }, "price": { "title": "AccommodationReservationPriceOutput", "description": "The price components of this accommodation order.", "type": "object", "properties": { "commissionable": { "description": "The commissionable price. Reservation price on which commission amount is calculated.", "nullable": true, "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "total": { "description": "The total price. Includes all extra charges.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } }, "nullable": true }, "products": { "type": "array", "items": { "title": "OrdersDetailsAccommodationsProductsOutput", "description": "The returned information of the product reserved.", "type": "object", "properties": { "allocation": { "title": "OrdersDetailsAccommodationsPropertiesOutput", "description": "The allocation of guests, adults and children for this product.", "type": "object", "properties": { "guests": { "description": "The number of guests reserved for this product.", "type": "integer", "minimum": 1 }, "adults": { "description": "The number of adults reserved for this product.", "type": "integer", "minimum": 1, "nullable": true }, "children": { "description": "The list of ages of all children reserved for this product.", "type": "array", "items": { "description": "The age of a child", "type": "integer", "maximum": 17 }, "nullable": true } } }, "bundle": { "title": "BundlePostBookOutput", "type": "object", "description": "A bundle attached to the reservation that includes information about the value-added service in the specified language.", "properties": { "id": { "type": "integer", "description": "Bundle identifier" }, "value_adds": { "type": "array", "items": { "title": "ValueAddPostBookOutput", "type": "object", "description": "Value-added service with its type and descriptive text localised in specified language.", "properties": { "type": { "description": "Identifies the type of value-added benefit included in the bundle, such as complimentary services, monetary credits, percentage discounts, or experiential amenities. Enum values encode how the benefit is applied, including time scope (per day or per stay) and unit scope (per room or per adult).", "type": "string", "enum": [ "parking", "food_drink_credit_per_day_per_room", "food_drink_credit_per_day_per_adult", "property_credit_per_day_per_room", "food_drink_credit_per_stay_per_adult", "food_drink_credit_per_stay_per_room", "property_credit_per_day_per_adult", "property_credit_per_stay_per_adult", "property_credit_per_stay_per_room", "food_drink_discount", "property_discount", "early_checkin", "late_checkout", "late_checkin", "spa_daily", "spa_hourly", "spa_massage", "high_speed_internet", "airport_transfer", "safari_game_drive", "safari_walk", "pets_stay", "bottle_of_wine", "bottle_of_champagne", "park_sleep_fly" ] }, "description": { "type": "array", "description": "Translated descriptive text in the requested language.", "items": { "type": "string" } } } } } } }, "guests": { "description": "The guest details for this product.", "type": "array", "items": { "title": "GuestOutput", "type": "object", "properties": { "email": { "description": "The email address of the guest.", "type": "string", "nullable": true }, "name": { "description": "The name of the guest.", "type": "string" } } } }, "policies": { "title": "AccommodationDetailsProductPoliciesOutput", "description": "The policies for this product. Requires `{\"extras\":[\"policies\"]}`.", "type": "object", "properties": { "cancellation": { "nullable": true, "description": "The cancellation policy schedule for this product.", "type": "array", "items": { "title": "AccommodationsProductDetailedCancellationPolicyMultiCurrency", "type": "object", "properties": { "from": { "description": "The time from which this cancellation fee applies. `now` means from booking time.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "now" }, { "type": "null" } ] }, "price": { "description": "The cancellation fee.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } } }, "meal_plan": { "title": "AccommodationsProductMealPlanPolicy", "description": "The meal plan policy for this product.", "type": "object", "properties": { "meals": { "description": "The meals included in the meal plan.", "type": "array", "items": { "type": "string", "enum": [ "breakfast", "dinner", "lunch" ] } }, "plan": { "description": "The meal plan included in this product.", "type": "string", "enum": [ "all_inclusive", "breakfast_included", "full_board", "half_board", "no_plan" ] } } }, "smoking_preference": { "description": "Smoking Preference for this product.", "type": "string", "enum": [ "smoking", "non-smoking" ], "nullable": true } } }, "price": { "title": "AccommodationDetailsProductPriceOutput", "description": "The price components of this product. 'extra_charges' are returned only when explicitly requested (via 'extras=extra_charges').", "type": "object", "properties": { "base": { "description": "The base price. It does not include any extra charges.", "nullable": true, "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "extra_charges": { "title": "OrdersProductExtraChargesOutput", "description": "The charge breakdown. Includes taxes and fees.", "type": "object", "properties": { "conditional": { "description": "Charges that might apply under a specific condition.", "type": "array", "items": { "title": "AccommodationsConditionalChargeMultiCurrency", "description": "Charges that might apply under a specific condition.", "type": "object", "properties": { "charge": { "description": "A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 0 }, "condition": { "description": "A signed integer number that uniquely identifies the condition ID. Find the full list in the Pricing guidelines.", "type": [ "integer", "null" ], "minimum": 0 }, "mode": { "description": "The mode of this charge. Determines how the price is calculated.", "type": "string", "enum": [ "calculated_amount", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay" ] }, "percentage": { "description": "The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "total_amount": { "description": "The total price for this charge.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "unit_amount": { "description": "The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.", "nullable": true, "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } } }, "non_conditional": { "description": "All non-conditional charges that will necessarily be paid", "type": "array", "items": { "title": "AccommodationsChargeMultiCurrency", "description": "All non-conditional charges that will necessarily be paid", "type": "object", "properties": { "charge": { "description": "A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.", "type": "integer", "minimum": 0 }, "mode": { "description": "The mode of this charge. Determines how the price is calculated.", "type": "string", "enum": [ "calculated_amount", "incalculable", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay" ] }, "percentage": { "description": "The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0, "nullable": true }, "total_amount": { "description": "The total price for this charge.", "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "unit_amount": { "description": "The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.", "nullable": true, "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } }, "nullable": true } } }, "total": { "description": "The total price. Includes all extra charges.", "nullable": true, "title": "AccommodationsPriceCurrency", "type": "object", "properties": { "accommodation_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } }, "room": { "description": "The room id given to this product.", "type": "number" }, "room_details": { "title": "RoomDetailsOutput", "description": "Room details for this product (via 'extras=accommodation_details').", "type": "object", "properties": { "name": { "description": "The room name given to this product.", "type": "string" } } }, "room_reservation": { "description": "The room reservation id given to this product.", "type": "number" }, "status": { "description": "Status of the product.", "type": "string", "enum": [ "booked", "cancelled", "cancelled_by_accommodation", "cancelled_by_guest", "no_show", "stayed" ] } } } }, "reservation": { "description": "Reservation ID for given accommodation order.", "type": "integer", "format": "int64" }, "remarks": { "description": "Guest remarks added while creating order.", "type": "string" }, "status": { "description": "Status of this accommodation order.", "type": "string", "enum": [ "booked", "cancelled", "cancelled_by_accommodation", "cancelled_by_guest", "no_show", "stayed" ] }, "stay_probability": { "description": "Score that predicts the likelihood of a traveller's intent to stay, based on internal calculations. A score of 0 indicates the highest likelihood of cancellation, while a score of 1 represents the highest likelihood of the traveller staying. Note: This score may not always be available.", "type": "number", "format": "double", "multipleOf": 0.01, "minimum": 0, "maximum": 1, "nullable": true } } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": "509430129718799", "accommodation": 123456, "accommodation_details": { "email": "test_hotel@booking.com", "location": { "address": "111 Street Road", "city": 20089219, "coordinates": { "latitude": 11.923274, "longitude": -92.716188 }, "country": "us", "post_code": "NY 1234" }, "name": "Test Booking Hotel USA", "telephone": "+19876543210" }, "accommodation_order_references": [ "12345", "ABED2312" ], "booker": { "external_account": 13610217, "platform": "mobile" }, "cancellation_details": { "at": "2022-11-09T00:00:00+00:00", "fee": { "accommodation_currency": 170.01, "booker_currency": 186.87 }, "original_total_price": { "accommodation_currency": 170.01, "booker_currency": 186.87 } }, "checkin": "2022-11-10", "checkout": "2022-11-10", "commission": { "actual_amount": null, "actual_percentage": null, "estimated_amount": { "accommodation_currency": 17.5, "booker_currency": 19.23 } }, "credit_slip_number": "hsnl1223445", "currency": { "accommodation": "EUR", "booker": "USD" }, "inventory": { "third_party": false, "type": "sell" }, "key_collection_information": [ { "additional_instructions": "The keys are in a keybox located next to the front door.", "alternate_location": { "address": "abc", "city": "bdweb", "postal_code": "1015XX" }, "checkin_method": "someone_will_meet", "key_location": "key_location_at_the_property" } ], "label": "One123", "pin_code": "1234", "price": { "commissionable": { "accommodation_currency": 164.01, "booker_currency": 180.27 }, "total": { "accommodation_currency": 170.01, "booker_currency": 186.87 } }, "products": [ { "allocation": { "adults": 2, "children": [ 3, 4, 5 ], "guests": 5 }, "guests": [ { "email": "test.name@booking.com", "name": "Test Name" } ], "policies": { "cancellation": [ { "from": null, "price": { "accommodation_currency": 170.01, "booker_currency": 186.87 } } ], "meal_plan": { "meals": [ "breakfast" ], "plan": "breakfast_included" }, "smoking_preference": "non-smoking" }, "price": { "base": { "accommodation_currency": 170.01, "booker_currency": 186.87 }, "extra_charges": { "conditional": [], "non_conditional": [ { "charge": 142, "mode": "per_person_per_night", "percentage": null, "total_amount": { "accommodation_currency": 6, "booker_currency": 6.6 }, "unit_amount": { "accommodation_currency": 3, "booker_currency": 3.3 } }, { "charge": 21, "mode": "percentage", "percentage": 9, "total_amount": { "accommodation_currency": 14.04, "booker_currency": 15.43 }, "unit_amount": null }, { "charge": 22, "mode": "percentage", "percentage": 7, "total_amount": { "accommodation_currency": 10.92, "booker_currency": 12 }, "unit_amount": null } ] }, "total": { "accommodation_currency": 200.97, "booker_currency": 220.9 } }, "room": 12345, "room_details": { "name": "Double Deluxe Room" }, "room_reservation": 1234567890, "status": "booked" } ], "remarks": "We will need an extra cot. Need room on higher floor", "reservation": 12345678, "status": "booked", "stay_probability": 0.12 } ] } } } } } } }, "/orders/details/cars": { "post": { "summary": "Orders with car details", "description": "This endpoint returns car order details, sorted by `bookingDate` in descending order", "operationId": "/orders/details/cars", "parameters": [ { "in": "header", "name": "X-Affiliate-Id", "schema": { "type": "integer" }, "required": true, "description": "Include here your Affiliate identifier number" } ], "tags": [ "Orders" ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "title": "CarsDetailsInputByOrders", "type": "object", "properties": { "orders": { "description": "List of order IDs for which details should be returned.", "type": "array", "items": { "description": "Order ID for which details should be returned.", "type": "string" }, "maxItems": 100 }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "extras": { "description": "Optional extra information groups that the user can request. It should be passed as a JSON array with one or more items.", "type": "array", "items": { "type": "string", "enum": [ "policies" ] } } }, "required": [ "orders" ] }, { "title": "CarsDetailsInputByReservations", "type": "object", "properties": { "reservations": { "description": "List of reservation IDs for which details should be returned.", "type": "array", "items": { "description": "Order ID for which details should be returned.", "type": "string" }, "maxItems": 100 }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "extras": { "description": "Optional extra information groups that the user can request. It should be passed as a JSON array with one or more items.", "type": "array", "items": { "type": "string", "enum": [ "policies" ] } } }, "required": [ "reservations" ] } ] }, "example": { "currency": "USD", "extras": [ "policies" ], "orders": [ "123456789", "098765432" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "OrdersDetailsCarsOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "title": "OrdersDetailsCarsOutput", "description": "Object containing all the information related to car order.", "type": "object", "properties": { "id": { "description": "Order ID for this car order.", "type": "string" }, "affiliate": { "description": "The affiliate ID used for this order.", "type": "number" }, "commission": { "title": "OrderCommissionOutput", "description": "Commission details for the partner for this car order.", "type": "object", "properties": { "actual_amount": { "description": "Actual commission amount for this car order (`null` if value is not yet available).", "nullable": true, "title": "CarsPriceCurrency", "type": "object", "properties": { "depot_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "actual_percentage": { "description": "Actual commission percentage for this car order (`null` if value is not yet available).", "type": "number", "format": "double", "nullable": true }, "estimated_amount": { "description": "Estimated commission amount for this car order (`null` if the actual amount is given).", "nullable": true, "title": "CarsPriceCurrency", "type": "object", "properties": { "depot_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } }, "currency": { "title": "OrderCurrencyOutput", "description": "Depot and booker currencies (booker will be `null`, if the request did not specify the currency).", "type": "object", "properties": { "depot": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "booker": { "nullable": true, "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" } } }, "dropoff": { "description": "Drop-off depot location and time.", "type": "object", "properties": { "datetime": { "description": "Pickup/drop-off date and time. The specific time will only be available if the requester has access to personal information. Otherwise, it will be set to 00:00:00.", "example": "2023-11-01T11:05:00+00:00", "format": "date-time", "type": "string" } } }, "label": { "description": "Identifier associated with the car booking.", "type": "string", "nullable": true }, "pickup": { "description": "Pick up depot location and time.", "type": "object", "properties": { "datetime": { "description": "Pickup/drop-off date and time. The specific time will only be available if the requester has access to personal information. Otherwise, it will be set to 00:00:00.", "example": "2023-11-01T11:05:00+00:00", "format": "date-time", "type": "string" } } }, "price": { "title": "CarReservationPriceOutput", "description": "The price breakdown for this car order.", "type": "object", "properties": { "commissionable": { "description": "The commissionable price, representing the car rental cost used to calculate the commission amount.", "nullable": true, "title": "CarsPriceCurrency", "type": "object", "properties": { "depot_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "total": { "description": "The total price, including all extra charges.", "title": "CarsPriceCurrency", "type": "object", "properties": { "depot_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } }, "nullable": true }, "products": { "type": "array", "items": { "title": "OrdersDetailsCarsProductsOutput", "description": "The returned information of the product reserved.", "type": "object", "properties": { "car": { "description": "Related car id", "type": "integer", "minimum": 1 }, "policies": { "description": "The policies that apply to this product.", "type": "object", "properties": { "payment": { "description": "The payment policy that applies to this product.", "type": "object", "properties": { "timing": { "description": "The applied payment timing. For example 'pay_now'.", "type": "string", "enum": [ "pay_now", "pay_local", "unknown" ] } }, "required": [ "timing" ] } } }, "price": { "title": "CarDetailsProductPriceOutput", "description": "Detailed breakdown of the product's price components.", "type": "object", "properties": { "base": { "description": "The base price. This does not include any extra charges.", "nullable": true, "title": "CarsPriceCurrency", "type": "object", "properties": { "depot_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "total": { "description": "The total price including any extra charges.", "nullable": true, "title": "CarsPriceCurrency", "type": "object", "properties": { "depot_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "booker_currency": { "type": "number", "format": "double", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } } }, "status": { "description": "Status of the product.", "type": "string", "enum": [ "booked", "cancelled", "cancelled_by_accommodation", "cancelled_by_guest", "no_show", "stayed" ] } } } }, "reservation": { "description": "This is the reservation id for the car in this order.", "type": "integer", "format": "int64" }, "status": { "description": "Status of this car order.", "type": "string", "enum": [ "booked", "cancelled", "cancelled_by_accommodation", "cancelled_by_guest", "no_show", "stayed" ] } } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": "123456789", "affiliate": 1234567, "commission": { "actual_amount": { "depot_currency": 45.5, "booker_currency": 66.34 }, "actual_percentage": 0.25, "estimated_amount": { "depot_currency": 45.5, "booker_currency": 66.34 } }, "currency": { "depot": "EUR", "booker": "USD" }, "dropoff": { "date": "2025-10-18T00:00:00" }, "label": "One123", "pickup": { "date": "2025-10-15T00:00:00" }, "price": { "commissionable": { "depot_currency": 170.01, "booker_currency": 186.87 }, "total": { "depot_currency": 170.01, "booker_currency": 186.87 } }, "products": [ { "policies": { "payment": { "timing": "pay_now" } }, "price": { "base": { "depot_currency": 170.01, "booker_currency": 186.87 }, "total": { "depot_currency": 170.01, "booker_currency": 186.87 } }, "status": "booked" } ], "status": "booked" } ] } } } } } } }, "/orders/details/flights": { "post": { "summary": "Orders with flight details", "description": "Use this endpoint to retrieve detailed information for one or more flight orders. - You can request car order details either by **order ID** or by **reservation ID**. - The response includes all relevant information for each order, such as booking and cancellation details, commission, pricing, and optional extras (for example, policies). Results are sorted by `bookingDate` in descending order, with the most recently booked orders listed first. It returns structured order data, including pricing, itinerary segments with IATA airport codes, etc.

This endpoint is ideal for:

- Displaying flight booking details in traveller dashboards or confirmation pages.
- Generating post-booking communications and invoices.
- Performing reporting or reconciliation tasks that require accurate itinerary and pricing data.", "operationId": "/orders/details/flights", "parameters": [ { "in": "header", "name": "X-Affiliate-Id", "schema": { "type": "integer" }, "required": true, "description": "Include here your Affiliate identifier number" } ], "tags": [ "Orders" ], "requestBody": { "content": { "application/json": { "schema": { "title": "FlightsDetailsInput", "type": "object", "properties": { "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" } }, "oneOf": [ { "title": "FlightsDetailsInputByOrders", "properties": { "orders": { "description": "List of order IDs for which details should be returned. Mutually exclusive with 'reservations'.", "type": "array", "items": { "type": "string", "description": "Flight order id for which details have to be returned." }, "maxItems": 100 } }, "required": [ "orders" ], "example": { "currency": "EUR", "orders": [ "1234567890123456", "9876543210987654" ] } }, { "title": "FlightsDetailsInputByReservations", "properties": { "reservations": { "description": "List of reservation IDs for which details should be returned. Mutually exclusive with 'orders'.", "type": "array", "items": { "type": "string", "description": "Flight reservation id for which details have to be returned." }, "maxItems": 100 } }, "required": [ "reservations" ], "example": { "currency": "EUR", "reservations": [ "2321873123", "4666773123" ] } } ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "OrdersDetailsFlightsOutput", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "FlightsOutput", "type": "object", "properties": { "id": { "description": "Order id", "type": "string" }, "reservation": { "description": "This is the reservation id for the travel service in this order.", "type": "string" }, "currency": { "title": "CurrencyOutput", "type": "object", "properties": { "booker_currency": { "description": "The currency of the booker.", "type": "string" }, "order_currency": { "description": "The currency in which the order was created.", "type": "string" } } }, "itineraries": { "type": "array", "items": { "title": "ItineraryOutput", "type": "object", "properties": { "arrival": { "description": "Arrival itinerary.", "title": "ItineraryPoint", "type": "object", "properties": { "airport": { "description": "A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling [common/locations/airports](#/common/locations/airports).", "pattern": "^[A-Z]{3}$", "type": "string" }, "date_time": { "description": "Date time of the itinerary.", "type": "string", "format": "date-time" } } }, "departure": { "description": "Departure itinerary.", "title": "ItineraryPoint", "type": "object", "properties": { "airport": { "description": "A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling [common/locations/airports](#/common/locations/airports).", "pattern": "^[A-Z]{3}$", "type": "string" }, "date_time": { "description": "Date time of the itinerary.", "type": "string", "format": "date-time" } } } } } }, "label": { "description": "Identifier associated with the order.", "type": "string" }, "price": { "title": "PriceOutput", "type": "object", "properties": { "booker_currency": { "description": "The price in the currency of the booker", "type": "number", "format": "double" }, "order_currency": { "description": "The price in the currency in which order was created", "type": "number", "format": "double" } } }, "status": { "type": "string", "enum": [ "booked", "cancelled", "unknown" ] } } } }, "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" } } }, "example": { "data": [ { "id": "ORDER_ID", "reservation": "RESERVATION_ID", "currency": { "booker": "EUR", "order": "USD" }, "itineraries": [ { "departure": { "airport": "CAI", "date_time": "2024-03-01T07:00:00+00:00" }, "arrival": { "airport": "LXR", "date_time": "2024-03-01T08:10:00+00:00" } } ], "label": "SAMPLE LABEL", "price": { "order_currency": 212.86, "booker_currency": 197.87 }, "status": "booked" } ] } } } } } } }, "/orders/modify": { "post": { "summary": "Modify an order", "description": "Use this endpoint to modify certain aspects of an accommodation order, such as credit card details, checkin/checkout dates, and room configurations (guest allocation, guest names, and smoking preferences). \n - See the [Orders modification guide](/demand/docs/orders-api/order-modify) for examples and best practices.\n", "operationId": "/orders/modify", "tags": [ "Orders" ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "title": "AccommodationModification", "type": "object", "properties": { "order": { "type": "string", "description": "Order ID to be modified" }, "modification": { "type": "object", "properties": { "accommodation": { "type": "object", "properties": { "reservation": { "type": "integer", "description": "Reservation ID" }, "change": { "oneOf": [ { "title": "DateChange", "type": "object", "properties": { "checkin": { "type": "string", "format": "date", "description": "New checkin date" }, "checkout": { "type": "string", "format": "date", "description": "New checkout date" } }, "required": [ "checkin", "checkout" ] }, { "title": "RoomChange", "type": "object", "properties": { "room_reservation": { "type": "integer", "format": "int64", "description": "Room reservation ID" }, "allocation": { "type": "object", "properties": { "number_of_adults": { "type": "integer" } } }, "guests": { "description": "Guest information for the room.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } } } }, "smoking_preference": { "type": "string", "enum": [ "no_preference", "non_smoking", "smoking" ] } } } ] }, "type": { "description": "Type of the accommodation change", "type": "string", "enum": [ "dates", "room" ] } }, "required": [ "reservation", "type", "change" ] } }, "required": [ "accommodation" ] } }, "required": [ "order", "modification" ] }, { "title": "PaymentModification", "type": "object", "properties": { "order": { "type": "string", "description": "Order ID to be modified" }, "modification": { "type": "object", "properties": { "payment": { "type": "object", "properties": { "change": { "type": "object", "properties": { "cardholder": { "type": "string", "description": "Cardholder name" }, "cvc": { "type": "string", "description": "A 3 or 4 digit Card Verification Code (CVC) associated with the used card" }, "expiry_date": { "type": "string", "format": "YYYY-MM", "description": "Card expiry date" }, "number": { "type": "string", "description": "Card number" } }, "required": [ "cardholder", "cvc", "expiry_date", "number" ] }, "type": { "description": "Type of the payment change", "type": "string", "enum": [ "card" ] } }, "required": [ "type", "change" ] } }, "required": [ "payment" ] } }, "required": [ "order", "modification" ] } ] } } } }, "responses": { "200": { "description": "Successful modification", "content": { "application/json": { "schema": { "oneOf": [ { "title": "AccommodationModificationResponse", "type": "object", "properties": { "modification": { "type": "object", "properties": { "accommodation": { "type": "object", "properties": { "new_price": { "description": "New price to be paid after the modification", "type": "number", "format": "double" }, "status": { "description": "Status for this modification request.", "type": "string", "enum": [ "successful", "failed" ] } } } } } } }, { "title": "PaymentModificationResponse", "type": "object", "properties": { "modifications": { "type": "object", "properties": { "payment": { "type": "object", "properties": { "status": { "description": "Status for this modification request.", "type": "string", "enum": [ "successful", "failed" ] } } } } } } } ] } } } } } } }, "/orders/cancel": { "post": { "summary": "Cancel an order", "description": "Use this endpoint to process an order cancellation. Refer to the [Cancellations guide](/demand/docs/orders-api/cancel-order) for instructions, tips and examples.", "operationId": "/orders/cancel", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Orders" ], "requestBody": { "content": { "application/json": { "schema": { "title": "OrdersCancelInput", "type": "object", "properties": { "order": { "description": "ID of the order to cancel.", "type": "string" }, "reason": { "description": "The reason for cancelling this order.", "type": "string" }, "request_property_approval": { "description": "(accommodations only) If the reservation has a cancellation fee, request the property to waive the fee and cancel for free. Subject to approval by the property.", "type": "string" } }, "required": [ "order", "reason" ] }, "example": { "order": "509430129718799", "reason": "I would like to book another property instead of this one." } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "OrdersCancelOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "title": "OrdersCancelDataOutput", "type": "object", "properties": { "status": { "description": "Status for this cancellation request.", "type": "string", "enum": [ "successful", "failed" ] } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": { "status": "successful" } } } } } } } }, "/cars/search": { "post": { "description": "Use this endpoint to retrieve the available car rentals matching the search criteria.", "summary": "Search car rentals", "operationId": "/search", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Cars" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "booker": { "description": "Defines the booker context.", "type": "object", "properties": { "country": { "description": "The booker country for showing the best price for that user and obeying laws regarding the display of taxes and fees.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" } }, "required": [ "country" ] }, "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "driver": { "description": "Defines the driver context.", "type": "object", "properties": { "age": { "description": "Driver age. Affect the availability and price of the products.", "type": "integer", "minimum": 18, "maximum": 99 } }, "required": [ "age" ] }, "filters": { "description": "Defines the filtering criteria for refining the request results. It allows you to specify various parameters to narrow down the available car rental options based on specific attributes.", "type": "object", "properties": { "air_conditioning": { "description": "Filters the results to include car rentals with or without air conditioning. Setting this value to true will only return vehicles with air conditioning, while false will exclude them.", "type": "boolean" }, "car_categories": { "description": "Filters the result based on the selected car category.", "items": { "oneOf": [ { "const": "carrier", "description": "Vans or minivans designed for carrying larger groups or luggage." }, { "const": "estate", "description": "Station wagons or estate cars offering extra luggage space." }, { "const": "large", "description": "Large vehicles offering ample interior space and comfort." }, { "const": "medium", "description": "Mid-sized vehicles offering a balance of comfort and fuel efficiency." }, { "const": "premium", "description": "High-end or luxury vehicles with premium features." }, { "const": "small", "description": "Compact cars ideal for city driving and short distances." }, { "const": "suvs", "description": "Sport Utility Vehicles offering higher ground clearance and versatility." } ] } }, "depot_location_type": { "description": "Indicates the specific type of location where the car rental depot is situated. This helps you accurately inform travellers about the nature of the pick-up point—whether it's located inside an airport terminal, at a train station, in a downtown area, or elsewhere. This field is optional and may be null if the location type is not defined.", "items": { "oneOf": [ { "const": "in_terminal", "description": "Depot is located inside the airport terminal building." }, { "const": "car_rental_centre", "description": "Depot is located in a dedicated car rental centre on or near airport grounds." }, { "const": "outside_terminal", "description": "Depot is outside the terminal area, usually a short walk or drive away." }, { "const": "airport_hotel", "description": "Depot is located at or inside an airport hotel." }, { "const": "shuttle_bus", "description": "Depot requires a shuttle bus transfer from the airport or another meeting point." }, { "const": "meet_greet", "description": "A rental agent meets the traveller in person at an agreed pick-up point (e.g., arrivals hall)." }, { "const": "trainstation", "description": "Depot is located in or near a train station." }, { "const": "downtown", "description": "Depot is located in a central/downtown city area." } ] } }, "mileage_type": { "description": "Filters the results based on the mileage type associated with the rental vehicle", "type": "string", "enum": [ "limited", "unlimited" ] }, "number_of_seats": { "description": "Filters the results based on the number of seats in the vehicle. This allows you to specify a vehicle that can accommodate a specific number of passengers.", "type": "integer" }, "supplier_ids": { "description": "Filters the results based on the supplier ID of the vehicle. This allows you to retrieve vehicles from specific suppliers. A maximum of 10 supplier IDs can be provided.", "type": "array", "items": { "description": "Supplier id.", "type": "integer" } }, "transmission_type": { "description": "Filters the results based on the transmission type of the vehicle.", "type": "string", "enum": [ "automatic", "manual" ] } } }, "maximum_results": { "default": 100, "description": "The maximum number of results to return per page.", "type": "integer", "multipleOf": 10, "minimum": 10, "maximum": 500 }, "language": { "description": "Effects on the selected language of the target website after redirection by provided url.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" }, "payment": { "description": "Payment-related input filters that allow you to narrow down car search results based on the payment timing options.", "type": "object", "properties": { "timings": { "description": "Filters the results to include only car rentals that offer the specified payment timings. Use this parameter to search for cars based on the timing of payment (e.g., payment upfront, partial payment, or payment at the depot).", "type": "array", "items": { "type": "string", "enum": [ "pay_now", "part_pay", "pay_local" ] } } } }, "route": { "description": "Defines the route context.", "type": "object", "properties": { "dropoff": { "description": "Drop off location and time.", "type": "object", "properties": { "datetime": { "description": "Pick up / drop off datetime.", "example": "2025-11-10T11:05:00", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$" }, "location": { "description": "Pick up / drop off location.", "oneOf": [ { "title": "Aeroport", "description": "Defines location of the related route point by airport.", "type": "object", "properties": { "airport": { "description": "A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling common/locations/airports.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "AMS" } } }, { "description": "Defines location of the related route point by coordinates.", "title": "Coordinates", "type": "object", "properties": { "coordinates": { "description": "Defines the geographic coordinates of the searched location.", "title": "Coordinates", "type": "object", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } } } } }, { "description": "Defines location of the related route point by city.", "title": "City", "type": "object", "properties": { "city": { "description": "A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.", "type": "integer" } } } ] } }, "required": [ "datetime", "location" ] }, "pickup": { "description": "Pick up location and time.", "type": "object", "properties": { "datetime": { "description": "Pick up / drop off datetime.", "example": "2025-11-05T11:05:00", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$" }, "location": { "description": "Pick up / drop off location.", "oneOf": [ { "description": "Defines location of the related route point by airport.", "type": "object", "properties": { "airport": { "description": "A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling common/locations/airports.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "AMS" } } }, { "description": "Defines location of the related route point by coordinates.", "type": "object", "properties": { "coordinates": { "description": "Defines the geographic coordinates of the searched location.", "title": "Coordinates", "type": "object", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } } } } }, { "description": "Defines location of the related route point by city.", "type": "object", "properties": { "city": { "description": "A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.", "type": "integer" } } } ] } }, "required": [ "datetime", "location" ] } }, "required": [ "dropoff", "pickup" ] }, "sort": { "description": "The sorting parameters for the response.", "type": "object", "properties": { "by": { "description": "The way to sort your results.", "type": "string", "enum": [ "distance", "price", "review_score" ] }, "direction": { "description": "The direction you wish for your sort.by parameter to be sorted in.", "type": "string", "enum": [ "ascending", "descending" ] } } } }, "required": [ "booker", "currency", "driver", "route" ] }, "examples": { "searchByAirport": { "summary": "Search example by airport.", "value": { "booker": { "country": "nl" }, "currency": "EUR", "driver": { "age": 36 }, "route": { "dropoff": { "datetime": "2025-11-10T11:05:00", "location": { "airport": "AMS" } }, "pickup": { "datetime": "2025-11-05T11:05:00", "location": { "airport": "AMS" } } } } }, "searchByCoordinatesWithResponseLimit": { "summary": "Search example by coordinates and max response limit up to 100 products.", "value": { "booker": { "country": "nl" }, "currency": "EUR", "driver": { "age": 36 }, "route": { "dropoff": { "datetime": "2025-11-10T11:05:00", "location": { "coordinates": { "latitude": 52.309456, "longitude": 4.762266 } } }, "pickup": { "datetime": "2025-11-05T11:05:00", "location": { "coordinates": { "latitude": 52.309456, "longitude": 4.762266 } } } }, "maximum_results": 100 } }, "searchByCityIdWithSorting": { "summary": "Search example by city id, filters and sorting by price.", "value": { "booker": { "country": "nl" }, "currency": "EUR", "driver": { "age": 36 }, "filters": { "transmission_type": "automatic", "mileage_type": "limited", "depot_location_type": "in_terminal" }, "route": { "dropoff": { "datetime": "2025-11-10T11:05:00", "location": { "city": -2140479 } }, "pickup": { "datetime": "2025-11-05T11:05:00", "location": { "city": -2140479 } } }, "sort": { "by": "price", "direction": "descending" } } }, "filterbypayment": { "summary": "Search by payment timing.", "value": { "booker": { "country": "nl" }, "currency": "EUR", "driver": { "age": 36 }, "route": { "dropoff": { "datetime": "2025-11-10T11:05:00", "location": { "city": -2140479 } }, "pickup": { "datetime": "2025-11-05T11:05:00", "location": { "city": -2140479 } } }, "payment": { "timings": "pay_now" } } }, "filterbydepotlocation": { "summary": "Filter results by depot location.", "value": { "booker": { "country": "nl" }, "currency": "EUR", "driver": { "age": 36 }, "route": { "dropoff": { "datetime": "2025-11-10T11:05:00", "location": { "city": -2140479 } }, "pickup": { "datetime": "2025-11-05T11:05:00", "location": { "city": -2140479 } } }, "filters": { "depot_location_type": "in_terminal" } } }, "multiplefilters": { "summary": "Use multiple filters in one request.", "value": { "booker": { "country": "nl" }, "currency": "EUR", "driver": { "age": 36 }, "route": { "dropoff": { "datetime": "2025-11-12T10:00:00", "location": { "city": -2140479 } }, "pickup": { "datetime": "2025-11-01T10:00:00", "location": { "city": -2140479 } } }, "filters": { "depot_location_type": "car_rental_centre", "number_of_seats": 7, "air_conditioning": true } } } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "description": "Detailed information about car rental product.", "type": "object", "properties": { "car": { "description": "Related car id", "type": "integer", "minimum": 1 }, "deal": { "title": "Deal", "description": "This specifies the deal tagging for the product.", "type": [ "object", "null" ], "properties": { "discount_percentage": { "description": "Discount percentage of the applied deals.", "type": "integer", "minimum": 1 }, "public_price": { "description": "Original price of this product, before applying any discounts.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 }, "tags": { "description": "The tags of all the applied deals.", "type": "array", "items": { "type": "string", "enum": [ "black_friday", "getaway_deal", "mobile_rate" ] } } } }, "policies": { "description": "The policies that apply to this product.", "type": "object", "properties": { "cancellation": { "description": "The cancellation policy that applies to this product.", "type": "object", "properties": { "details": { "description": "Provides the policy details if the cancellation is free. For example: \n 1. duration='PT48H' and context=before_pickup means 'Free cancellation is available up to 48 hrs before pick up'. \n 2. duration='P7D' and context=within_given_time_period_of_booking means 'Free cancellation is available within 7 days of booking'", "type": [ "object", "null" ], "properties": { "context": { "description": "The context in which the cancellation policy applies. For example 'before_pickup'", "type": "string", "enum": [ "before_pickup", "within_given_time_period_of_booking" ] }, "duration": { "description": "The duration until which the cancellation is free. This is in ISO-8601/Duration format.", "type": "string", "pattern": "^P(?:\\dY)?(?:\\dM)?(?:\\dD)?(?:T(?:\\dH)?(?:\\dM)?(?:\\dS)?)?$" } } }, "type": { "description": "The type of cancellation present. For example 'free_cancellation' or 'non_refundable'.", "type": "string", "enum": [ "free_cancellation", "non_refundable" ] } } }, "damage_excess": { "description": "The maximum amount a traveller may be charged for damages to the car during the rental period, as specified by the rental agreement.", "type": [ "number", "null" ], "format": "double" }, "deposit": { "description": "The amount of money that will be temporarily pre-authorised or blocked on the traveller’s credit card at the rental location as a security deposit, to cover potential damage or extra charges.", "type": [ "number", "null" ], "format": "double" }, "insurance_package": { "description": "The supplier insurance package that applies to this car rental product. Possible values:\n - `basic`: No insurance is included. The traveller is usually required to purchase coverage at the rental counter.\n - `inclusive`: Full protection is provided. Collision Damage Waiver (CDW) is included, limiting the traveller’s financial liability for damage.\n - `zero_excess`: Partial protection is provided. CDW is included, but some coverage elements (e.g., theft protection) may not be included, so the traveller could still be liable for certain costs.\n", "type": "string", "enum": [ "basic", "inclusive", "zero_excess" ] }, "fuel": { "description": "The fuel policy that applies to this product.", "type": "string", "enum": [ "return_same", "return_same_or_prepay_no_refunds", "return_same_preauth", "free_tank", "prepay_no_refunds", "prepay_part_refunds", "prepay_refunds" ] }, "mileage": { "description": "The mileage policy that applies to this product.", "type": "object", "properties": { "distance": { "description": "The maximal distance limit allowed for this product before additional fees apply.", "type": [ "integer", "null" ], "minimum": 0 }, "distance_unit": { "description": "The unit of measurement for the distance limit. For example 'km' or 'miles'.", "type": "string", "enum": [ "kilometers", "miles" ] }, "fee": { "description": "The fee that must be paid if the distance limit is exceeded.", "type": [ "number", "null" ], "format": "double" }, "type": { "description": "The type of mileage policy applied.", "type": "string", "enum": [ "limited", "unlimited" ] } }, "required": [ "fee", "type" ] }, "payment": { "description": "The payment policy that applies to this product.", "type": "object", "properties": { "timing": { "description": "The applied payment timing. For example 'pay_now'.", "type": "string", "enum": [ "pay_now", "part_pay", "pay_local" ] } }, "required": [ "timing" ] }, "theft_excess": { "description": "The maximum amount a traveller may be charged in the event of car theft during the rental period, as outlined in the rental agreement.", "type": [ "number", "null" ], "format": "double" } } }, "price": { "description": "The price components of this product.", "type": "object", "properties": { "currency": { "description": "A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }, "extra_charges": { "title": "CarsProductExtraCharges", "description": "The charge breakdown. Includes taxes and fees included in the drive away price.", "type": "array", "items": { "title": "CarsCharge", "description": "Defines the charge, including the type of charge and its total amount.", "type": "object", "properties": { "charge": { "description": "The type of this charge.", "type": "string", "enum": [ "age_fee", "one_way_fee" ] }, "total_amount": { "description": "The total price for this charge.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 } } } }, "total": { "description": "The total price. Includes all extra charges.", "type": "number", "multipleOf": 0.01, "exclusiveMinimum": 0 } } }, "route": { "description": "Defines the actual route associated with the product.", "type": "object", "properties": { "dropoff": { "description": "Defines the product drop off route point.", "type": "object", "properties": { "depot": { "description": "Pick up / drop off depot.", "type": "integer", "minimum": 1, "example": 5944 } } }, "pickup": { "description": "Defines the product pick up route point.", "type": "object", "properties": { "depot": { "description": "Pick up / drop off depot.", "type": "integer", "minimum": 1, "example": 5944 } } } } }, "supplier": { "description": "Related supplier id.", "type": "integer", "minimum": 1 }, "url": { "description": "Urls to the relevant pages.", "type": "object", "properties": { "app": { "description": "URL for the related page on Booking App.", "type": "string", "format": "uri" }, "web": { "description": "URL for the related page on cars.booking.com.", "type": "string", "format": "uri" } } } } } }, "metadata": { "title": "MetadataOutput", "description": "Metadata about the request.", "type": "object", "properties": { "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`).", "type": [ "string", "null" ] }, "total_results": { "description": "The total number of results available.", "type": "integer", "minimum": 0 } } }, "search_token": { "description": "Encoded string that must be passed in subsequent requests to identify the context of the car search. Note: It is specific to Car rentals and differs from other tokens used in booking flows.", "type": "string" } } }, "example": { "request_id": "01h00fr9y7qkbxtc6kyv97j49z", "data": [ { "car": 122655, "policies": { "cancellation": { "type": "free_cancellation", "details": { "context": "before_pickup", "duration": "P7D" } }, "damage_excess": 3000, "deposit": 1500, "insurance_package": "basic", "fuel": "return_same", "mileage": { "distance": 200, "distance_unit": "kilometers", "fee": 12.54, "type": "limited" }, "payment": { "timing": "pay_now" }, "theft_excess": 3000 }, "price": { "total": "121.90", "currency": "EUR", "extra_charges": [ { "charge": "age_fee", "total_amount": 21.9 }, { "charge": "one_way_fee", "total_amount": 50 } ] }, "route": { "dropoff": { "depot": 112314 }, "pickup": { "depot": 112314 } }, "supplier": 7455, "url": { "app": "booking://page", "web": "https://example.com" } } ], "metadata": { "next_page": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7Im1heGltdW1fcmVzdWx0cyI6MTAsIm9mZnNldCI6MTB9LCJhdWQiOiJDQVJTX1NVUFBMSUVSUyIsImV4cCI6MTY4MzY0NzMwNX0.y7NmH48mm7lImd2WxsHdotj6n-dVQAzJCGCnIJCKy3A", "total_results": 122 }, "search_token": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7ImJvb2tlciI6eyJjb3VudHJ5IjoidXMifX0sImF1ZCI6Ii9ob3RlbHMvc2VhcmNoIiwiZXhwIjoxNzUwMDAwMDAwfQ.XYZ123AbcDefGHIjklMNOpqrsTUVwxYZ456789" } } } } } } }, "/cars/depots": { "post": { "description": "Use this endpoint to retrieve the list of all available car rental depots.", "summary": "Depots", "operationId": "/depots", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Cars" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "last_modified": { "description": "The last modified date-time, only returns depots newer than this timestamp.", "example": "2025-11-01T11:05:00+00:00", "format": "date-time", "type": "string" }, "maximum_results": { "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "maximum": 100, "default": 100 }, "languages": { "type": "array", "items": { "description": "A [IETF language tag code](https://en.wikipedia.org/wiki/IETF_language_tag) that uniquely identifies a supported human language or dialect. **Note:** Demand API only accepts lowercase for the language codes. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "default": [ "en-gb" ] }, "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" } } }, "example": { "last_modified": "2025-11-01T11:05:00+00:00", "maximum_results": 100, "languages": [ "en-gb", "nl" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "description": "All static information related to car rental depot.", "properties": { "id": { "description": "Unique depot's ID.", "type": "integer", "minimum": 1, "example": 5944 }, "contact": { "description": "Contact information of the depot. It can be `null` if the data is missing.", "type": "object", "properties": { "email": { "description": "Email address of the depot. It can be `null` if the data is missing.", "example": "depot@test.booking.com", "type": [ "string", "null" ] }, "telephone": { "description": "Telephone number of the depot. It can be `null` if the data is missing.", "example": "+31882847620", "type": [ "string", "null" ] } } }, "city": { "description": "A signed integer number that uniquely identifies a city. You can see the full list of cities ids calling common/locations/cities.", "type": "integer", "example": -1471393 }, "drop_off": { "description": "Contains rented car drop off information.", "properties": { "instructions": { "description": "Drop off/pick up instructions.", "title": "TranslatedString", "type": [ "object", "null" ], "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "working_hours": { "description": "Depot's working hours.", "patternProperties": { "^(monday|tuesday|wednesday|thursday|friday|saturday|sunday)$": { "description": "Day working hours.", "items": { "description": "Describes depot working hours.", "properties": { "closing_time": { "description": "Depot's closing time", "example": "21:00", "format": "time", "type": "string" }, "opening_time": { "description": "Depot's opening time.", "example": "07:00", "format": "time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": [ "object", "null" ] } }, "type": "object" }, "location": { "description": "Depot location information.", "properties": { "address": { "description": "Depot address information.", "example": "5 Aankomstpassage", "type": [ "string", "null" ] }, "airport": { "description": "Airport IATA code.", "example": "AMS", "type": [ "string", "null" ] }, "city": { "description": "A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.", "type": "integer" }, "depot_location_type": { "description": "Indicates the specific type of location where the car rental depot is situated. This helps you accurately inform travellers about the nature of the pick-up point—whether it's located inside an airport terminal, at a train station, in a downtown area, or elsewhere. This field is optional and may be null if the location type is not defined.", "type": [ "string", "null" ], "enum": [ "in_terminal", "car_rental_centre", "outside_terminal", "airport_hotel", "shuttle_bus", "meet_greet", "trainstation", "downtown" ], "x-enumDescriptions": { "in_terminal": "Depot is located inside the airport terminal building.", "car_rental_centre": "Depot is located in a dedicated car rental centre on or near airport grounds.", "outside_terminal": "Depot is outside the terminal area, usually a short walk or drive away.", "airport_hotel": "Depot is located at or inside an airport hotel.", "shuttle_bus": "Depot requires a shuttle bus transfer from the airport or another meeting point.", "meet_greet": "A rental agent meets the traveller in person at an agreed pick-up point (e.g., arrivals hall).", "trainstation": "Depot is located in or near a train station.", "downtown": "Depot is located in a central/downtown city area." } }, "coordinates": { "title": "Coordinates", "type": "object", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } } }, "country": { "description": "A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.", "type": "string", "pattern": "^[a-z]{2}$", "example": "nl" }, "name": { "description": "Translated depot name.", "example": "Amsterdam Airport Schiphol - Terminal 3", "title": "TranslatedString", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "post_code": { "description": "Depot post code", "example": "1118 AX", "type": "string" } }, "type": "object" }, "pick_up": { "description": "Contains rented car pick up information.", "properties": { "instructions": { "description": "Drop off/pick up instructions.", "title": "TranslatedString", "type": [ "object", "null" ], "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } }, "working_hours": { "description": "Depot's working hours.", "patternProperties": { "^(monday|tuesday|wednesday|thursday|friday|saturday|sunday)$": { "description": "Day working hours.", "items": { "description": "Describes depot working hours.", "properties": { "closing_time": { "description": "Depot's closing time", "example": "21:00", "format": "time", "type": "string" }, "opening_time": { "description": "Depot's opening time.", "example": "07:00", "format": "time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } }, "type": "object" }, "services": { "description": "List of services provided by the depot.", "type": "array", "items": { "type": "string", "enum": [ "shuttle", "meet_greet", "unknown" ] } }, "supplier": { "description": "Related supplier id", "type": "integer", "minimum": 1 }, "ratings": { "description": "Number of reviews and average score for the depot.", "type": [ "object", "null" ], "properties": { "number_of_reviews": { "description": "Number of validated reviews for this depot.", "type": "integer", "minimum": 0 }, "score": { "description": "A decimal number indicating the current review score of this depot, in the range 1..10.", "type": "number", "multipleOf": 0.1, "minimum": 1, "maximum": 10 } } } }, "type": "object" } }, "metadata": { "description": "Metadata about the request.", "type": "object", "properties": { "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`).", "type": [ "string", "null" ] } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 5944, "contact": { "email": "depot@test.booking.com", "telephone": "+31882847620" }, "city": "-1471393", "drop_off": { "instructions": { "en-gb": "The procedure for returning the vehicle will be explained to you at the rental counter.", "de": "De procedure voor het inleveren van de auto zal worden toegelicht aan de balie." }, "working_hours": { "monday": [ { "closing_time": "21:00:00", "opening_time": "07:00:00" } ], "tuesday": [ { "closing_time": "12:00:00", "opening_time": "07:00:00" }, { "closing_time": "21:00:00", "opening_time": "14:00:00" } ], "wednesday": [ { "closing_time": "21:00:00", "opening_time": "07:00:00" } ], "thursday": [ { "closing_time": "21:00:00", "opening_time": "07:00:00" } ], "friday": [ { "closing_time": "21:00:00", "opening_time": "07:00:00" } ], "saturday": [ { "closing_time": "21:00:00", "opening_time": "07:00:00" } ], "sunday": [ { "closing_time": "21:00:00", "opening_time": "07:00:00" } ] } }, "location": { "address": "5 Aankomstpassage", "airport": "AMS", "city": -2140479, "coordinates": { "latitude": 52.309456, "longitude": 4.762266 }, "country": "nl", "depot_location_type": "airport_hotel", "name": { "en-gb": "Amsterdam Airport Schiphol - Terminal 3", "de": "Amsterdam Luchthaven Schiphol - Terminal 3" }, "post_code": "1118 AX" }, "pick_up": { "instructions": { "en-gb": "-", "de": "-" }, "working_hours": { "monday": [ { "closing_time": "21:00:00", "opening_time": "07:00:00" } ], "tuesday": [ { "closing_time": "12:00:00", "opening_time": "07:00:00" }, { "closing_time": "21:00:00", "opening_time": "14:00:00" } ], "wednesday": [ { "closing_time": "21:00:00", "opening_time": "07:00:00" } ], "thursday": [ { "closing_time": "21:00:00", "opening_time": "07:00:00" } ], "friday": [ { "closing_time": "21:00:00", "opening_time": "07:00:00" } ], "saturday": [ { "closing_time": "21:00:00", "opening_time": "07:00:00" } ], "sunday": [ { "closing_time": "21:00:00", "opening_time": "07:00:00" } ] } }, "services": [ "shuttle" ], "supplier": 47 } ], "metadata": { "next_page": null } } } } } } } }, "/cars/depots/reviews/scores": { "post": { "description": "Use this endpoint to return the score breakdown for the specified depots together with the overall number of reviews and score.

- Please note that the **ratings score is based on all traveller traffic across Booking.com/cars**, and may not necessarily reflect the experience of your own customers.

- If you choose to display or use these ratings, you are responsible for ensuring that your travellers are properly informed about what these scores represent.", "summary": "Depot scores", "operationId": "/depots/reviews/scores", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Cars" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "maximum_results": { "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "maximum": 100, "default": 100 }, "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" } } }, "example": { "maximum_results": 10 } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "description": "", "type": "object", "properties": { "id": { "description": "Uniquely identifies a depot. The full list can be obtained by calling [/cars/depots](#/cars/depots).", "type": "integer", "minimum": 1, "example": 5944 }, "breakdown": { "description": "Review scores breakdown for each criteria. List of criteria includes: cleanliness, condition, drop_off_speed, efficiency, expense, location, pick_up_speed.", "type": "object", "patternProperties": { "^(cleanliness|condition|drop_off_speed|friendliness|likeliness_rent_again|location|pick_up_speed|value_for_money)$": { "type": "object", "properties": { "score": { "description": "A decimal number indicating the review score of this criteria, in the range 1..10.", "type": [ "number", "null" ], "multipleOf": 0.1, "minimum": 1, "maximum": 10 } } } } }, "number_of_reviews": { "description": "Number of validated reviews for this depot.", "type": [ "integer", "null" ], "minimum": 0 }, "score": { "description": "A decimal number indicating the current review score of this depot, in the range 1..10.", "type": [ "number", "null" ], "multipleOf": 0.1, "minimum": 1, "maximum": 10 } } } }, "metadata": { "description": "Metadata about the request.", "type": "object", "properties": { "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`).", "type": [ "string", "null" ] } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 5944, "breakdown": { "cleanliness": { "score": 8.7 }, "condition": { "score": 8.7 }, "drop_off_speed": { "score": 8.7 }, "friendliness": { "score": null }, "likeliness_rent_again": { "score": 8.7 }, "location": { "score": 8.7 }, "pick_up_speed": { "score": 8.7 }, "value_for_money": { "score": 8.7 } }, "number_of_reviews": 105, "score": 9.1 } ], "metadata": { "next_page": null } } } } } } } }, "/cars/details": { "post": { "description": "Use this endpoint to fetch car details like bag capacity, number of doors, brand and model, etc.", "summary": "Car details", "operationId": "/details", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Cars" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "last_modified": { "description": "The last modified date-time, only returns depots newer than this timestamp. The value should be within last 7 days", "example": "2025-12-01T11:05:00+00:00", "format": "date-time", "type": "string" }, "maximum_results": { "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "maximum": 100, "default": 100 }, "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" } } }, "example": { "last_modified": "2025-12-01T11:05:00+00:00", "maximum_results": 100 } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "description": "All static information related to cars.", "properties": { "id": { "description": "Unique car's ID.", "type": "integer", "minimum": 1 }, "capacity": { "description": "Car's capacity", "type": "object", "properties": { "bags": { "description": "Car's baggage capacity.", "type": [ "object", "null" ], "properties": { "large": { "description": "Number of large bags.", "type": "number", "minimum": 0 }, "small": { "description": "Number of small bags.", "type": "number", "minimum": 0 } } }, "doors": { "description": "Number of doors in the car.", "type": "string" }, "seats": { "description": "Number of seats in the car.", "type": "string" } } }, "features": { "description": "List of possible car's features.", "type": "array", "items": { "type": "string", "enum": [ "air_conditioning", "all_wheel_drive" ] } }, "image": { "description": "Car's image URL.", "type": "string" }, "make": { "description": "Car's maker/brand.", "type": "string" }, "model": { "description": "Car's model.", "type": "string" }, "specification": { "description": "Car's specification.", "properties": { "code": { "description": "Car's code in [ACRISS Standard](https://www.acriss.org/car-codes/expanded-matrix/).", "type": "string" }, "description": { "description": "Car Description Based on [ACRISS Category and Type](https://www.acriss.org/car-codes/expanded-matrix/).", "type": "string" }, "fuel": { "description": "Car's fuel type.", "type": "string", "enum": [ "electric", "petrol", "plug_in_hybrid", "multi_fuel", "diesel", "hybrid", "lpg", "hydrogen", "ethanol", "unspecified" ] }, "transmission": { "description": "Car's transmission.", "type": "string", "enum": [ "automatic", "manual" ] } } }, "supplier": { "description": "Related supplier id.", "type": "integer", "minimum": 1 } }, "type": "object" } }, "metadata": { "description": "Metadata about the request.", "type": "object", "properties": { "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`).", "type": [ "string", "null" ] } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 37715, "capacity": { "bags": { "large": 1, "small": 1 }, "doors": "4/2", "seats": "4+2" }, "features": [ "air_conditioning", "all_wheel_drive" ], "image": "https://example.com/image.jpg", "make": "hyundai", "model": "elantra", "specification": { "code": "ECAR", "description": "economy", "fuel": "petrol", "transmission": "automatic" }, "supplier": 423 } ], "metadata": { "next_page": null } } } } } } } }, "/cars/suppliers": { "post": { "description": "Use this endpoint to fetch a list of car rental suppliers.
You can use a supplier ID (or an array of them), to retrieve specific details.
Alternatively, if you do not add any ID in the request, the response will include all suppliers.", "summary": "Suppliers", "operationId": "/suppliers", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Cars" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "maximum_results": { "description": "The maximum number of results to return.", "type": "integer", "multipleOf": 10, "minimum": 10, "maximum": 100, "default": 100 }, "page": { "description": "Pagination token used to retrieve the next page of results. Obtained from `next_page`.", "type": "string" }, "suppliers": { "description": "Defines the suppliers that should be returned. Without it all suppliers will be returned", "type": "array", "items": { "description": "Uniquely identifies a vehicle supplier. The full list can be obtained by calling /cars/suppliers.", "type": "integer", "minimum": 1 }, "maxItems": 100 } } }, "example": { "suppliers": [ 62 ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "array", "items": { "description": "All static information related to an vehicle supplier.", "type": "object", "properties": { "id": { "description": "Uniquely identifies a vehicle supplier. The full list can be obtained by calling /cars/suppliers.", "type": "integer", "minimum": 1 }, "logo": { "description": "Supplier logo image URL.", "type": "string", "format": "uri" }, "name": { "description": "Brand name of the vehicle supplier.", "type": "string" } } } }, "metadata": { "title": "MetadataOutput", "description": "Metadata about the request.", "type": "object", "properties": { "next_page": { "description": "Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter `page`).", "type": [ "string", "null" ] }, "total_results": { "description": "The total number of results available.", "type": "integer", "minimum": 0 } } } } }, "example": { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 62, "name": "Budget", "logo": "https://example.com/path_to_the_logo.jpeg" } ], "metadata": { "next_page": null, "total_results": 1 } } } } } } } }, "/cars/constants": { "post": { "summary": "Car constants", "description": "This endpoint returns a list of relevant car constants names in the specified languages. For example, calling with the parameters {\"languages\":\"en-us\",\"fr\"} will return the list in English (US) and French. To retrieve the full list, make the request with an empty body.", "operationId": "/constants", "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "tags": [ "Cars" ], "requestBody": { "content": { "application/json": { "schema": { "title": "CarsConstantsInput", "type": "object", "properties": { "constants": { "description": "A list of car rental constant types to filter the results by. This allows you to narrow down the result based on particular criteria, such as fuel_policy, payment_timings etc.", "type": "array", "items": { "type": "string", "enum": [ "depot_services", "fuel_policies", "fuel_types", "general", "payment_timings", "transmission" ] } }, "languages": { "type": "array", "items": { "description": "A [IETF language tag code](https://en.wikipedia.org/wiki/IETF_language_tag) that uniquely identifies a supported human language or dialect. **Note:** Demand API only accepts lowercase for the language codes. Examples: \"nl\" for Dutch/Nederlands or \"en-us\" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint in the same Demand API version you are using.", "type": "string", "pattern": "^[a-z]{2}(-[a-z]{2})?$", "example": "en-us" }, "default": [ "en-gb" ] } } }, "example": { "languages": [ "de", "en-gb" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "title": "CarsConstantsOutput", "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "title": "ConstantsDataOutput", "type": "object", "properties": { "depot_services": { "title": "CarsConstant", "description": "Id and translated names for the constant.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } }, "fuel_policies": { "title": "CarsConstant", "description": "Id and translated names for the constant.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } }, "fuel_types": { "title": "CarsConstant", "description": "Id and translated names for the constant.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } }, "general": { "title": "CarsConstant", "description": "Id and translated names for the constant.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } }, "payment_timings": { "title": "CarsConstant", "description": "Id and translated names for the constant.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } }, "transmission": { "title": "CarsConstant", "description": "Id and translated names for the constant.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "title": "TranslatedString", "description": "A string localised in multiple languages.", "type": "object", "patternProperties": { "^[a-z]{2}(-[a-z]{2})$": { "description": "The content localised in this language.", "type": [ "string", "null" ] } } } } } } } } }, "example": { "request_id": "01jpvx9va93ghgwxq7zypagvdr", "data": { "depot_services": [ { "id": "meet_greet", "name": { "de": "Meet & Greet", "en-gb": "Meet & Greet" } }, { "id": "shuttle", "name": { "de": "Shuttlebus", "en-gb": "Shuttle Bus" } } ], "fuel_policies": [ { "id": "free_tank", "name": { "de": "Kostenlose Tankfüllung", "en-gb": "Free Tank" } }, { "id": "prepay_no_refunds", "name": { "de": "Vorab-Einkauf", "en-gb": "Pre-Purchase" } }, { "id": "prepay_part_refunds", "name": { "de": "Vorab-Einkauf (Teilerstattung)", "en-gb": "Pre-purchase (partial refund)" } }, { "id": "prepay_refunds", "name": { "de": "Vorab-Einkauf", "en-gb": "Pre-Purchase" } }, { "id": "return_same", "name": { "de": "Gleiche Tankfüllung", "en-gb": "Like for like" } } ], "fuel_types": [ { "id": "electric", "name": { "de": "Rein elektrisch", "en-gb": "Fully electric" } }, { "id": "hybrid", "name": { "de": "Hybrid", "en-gb": "Hybrid" } }, { "id": "petrol", "name": { "de": "Benzin", "en-gb": "Petrol" } }, { "id": "plug_in_hybrid", "name": { "de": "Plug-in-Hybrid", "en-gb": "Plug-in hybrid" } } ], "general": [ { "id": "air_conditioning", "name": { "de": "Flughafen (im Terminal)", "en-gb": "Airport (in terminal)" } }, { "id": "airport", "name": { "de": "Klimaanlage", "en-gb": "Air Conditioning" } }, { "id": "free_cancellation", "name": { "de": "Kostenlose Stornierung", "en-gb": "Free cancellation" } }, { "id": "kilometers", "name": { "de": "km", "en-gb": "km" } }, { "id": "limited", "name": { "de": "Begrenzt", "en-gb": "Limited" } }, { "id": "miles", "name": { "de": "Meilen", "en-gb": "miles" } }, { "id": "n_large_bags", "name": { "de": "N große Koffer", "en-gb": "N Large bags" } }, { "id": "n_small_bags", "name": { "de": "N kleine Koffer", "en-gb": "N Small bags" } } ], "payment_timings": [ { "id": "part_pay", "name": { "de": "Teils jetzt zahlen, teils später", "en-gb": "Pay part now, part later" } }, { "id": "pay_now", "name": { "de": "Jetzt zahlbar", "en-gb": "Pay now" } } ], "transmission": [ { "id": "automatic", "name": { "de": "Automatik", "en-gb": "Automatic" } }, { "id": "manual", "name": { "de": "Schaltgetriebe", "en-gb": "Manual" } } ] } } } } } } } }, "/messages/send": { "post": { "summary": "Send a message", "description": "Sends a message within a conversation. The message body supports plain text.\nOptionally, attach a file by referencing a previously uploaded attachment ID.\n", "operationId": "sendMessage", "tags": [ "Messages" ], "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "SendMessageRequest", "type": "object", "required": [ "conversation", "content", "accommodation" ], "properties": { "conversation": { "type": "string", "description": "Unique identifier of the conversation." }, "accommodation": { "type": "string", "description": "Unique identifier of the property." }, "content": { "type": "string", "description": "The message text to send." }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "Optional list of attachment IDs, if sending one or more files." } } }, "example": { "conversation": "8586a789-44f4-5521-9f27-f5efd097cba6", "accommodation": "6819547", "content": "Hello, I'm your guest!.", "attachments": [ "c325f460-1dc6-11f0-80f0-8d0908786f77" ] } } } }, "responses": { "200": { "description": "Message sent successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique identifier for this request. Provide this ID when contacting support." }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Unique identifier for the sent message." } } } } }, "example": { "request_id": "cdb0b154-2eae-481b-8fee-fb2725296e1f", "data": { "message": "3164e570-19e0-11f0-baca-e5019c8df435" } } } } } } } }, "/messages/conversations": { "post": { "summary": "Retrieve a conversation", "description": "Retrieves a conversation accessible to the authenticated user, including message history and participants.\n", "operationId": "retrieve-conversation", "tags": [ "Conversations" ], "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "RetrieveConversationRequest", "type": "object", "properties": { "accommodation": { "type": "string", "description": "Unique identifier of the property." } }, "required": [ "accommodation" ], "oneOf": [ { "required": [ "reservation" ], "title": "InputByreservation", "properties": { "reservation": { "type": "string", "description": "Unique identifier of the reservation." } } }, { "required": [ "conversation" ], "title": "InputByconversation", "properties": { "conversation": { "type": "string", "description": "Unique identifier of the conversation." } } } ] }, "examples": { "InputByconversation": { "summary": "Retrieve conversation based on accommodation and conversation ID.", "value": { "accommodation": "6819547", "conversation": "c3cc6522-aa63-559d-99f1-94efdd527c3c" } }, "InputByreservation": { "summary": "Retrieve conversation based on accommodation and reservation ID.", "value": { "accommodation": "6819547", "reservation": "4338284887" } } } } } }, "responses": { "200": { "description": "Conversation retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique identifier for this request. Provide this ID when contacting support." }, "data": { "type": "object", "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the conversation." }, "reservation": { "type": "string", "description": "Unique identifier of the reservation." }, "messages": { "type": "array", "description": "List of messages in the conversation.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the message." }, "sender": { "type": "string", "description": "Unique identifier of the sender." }, "reply_to": { "type": "string", "description": "Message ID this message replies to (if applicable)." }, "content": { "type": "string", "description": "Message text content." }, "attachments": { "type": "array", "items": { "type": "string", "description": "Attachment IDs included with the message." } }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp in ISO 8601 format (UTC) when the message was sent." } } } }, "participants": { "type": "array", "description": "List of participants in the conversation.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the participant." }, "metadata": { "type": "object", "description": "Additional participant metadata." } } } } } } } } } }, "example": { "request_id": "7889a8c0-aa43-494c-863d-72d2306849c1", "data": { "conversation": { "id": "c3cc6522-aa63-559d-99f1-94efdd527c3c", "reservation": "4338284887", "messages": [ { "id": "af3d7fd0-1c50-11f0-81cd-6d243d208da3", "sender": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f", "reply_to": "c3cc6522-aa63-559d-99f1-94efdd527c3c", "content": "Thank you for choosing Demand API Messaging Test Hotel. We are looking forward to your stay", "attachments": [], "timestamp": "2025-04-18T12:28:51.149Z" } ], "participants": [ { "id": "5dba2525-2c49-5d2c-91cc-7195526c0c7a", "metadata": { "type": "guest" } }, { "id": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f", "metadata": { "type": "property", "accommodation_id": "6819547" } } ] } } } } } } } } }, "/messages/latest": { "post": { "summary": "Fetch latest messages", "description": "Retrieves up to 100 of the most recent messages from a specified conversation, including messages from both property and guest.
\n\n- Messages are returned in reverse chronological order (newest first).\n- Use this endpoint to sync message threads or poll for updates.\n\n**Important:** This endpoint **does not accept a request body**. To retrieve the latest messages, send an empty POST request. \nAny content in the request body will be ignored.\n", "operationId": "fetchLatestMessages", "tags": [ "Messages" ], "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "responses": { "200": { "description": "Latest messages fetched successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique identifier for this request. Provide this ID when contacting support." }, "data": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "message_id": { "type": "string", "description": "Unique identifier of the message." }, "reply_to": { "type": "string", "description": "ID of the message this is replying to (if applicable)." }, "conversation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the conversation." }, "accommodation": { "type": "string", "description": "Unique identifier of the property." }, "reservation": { "type": "string", "description": "Unique identifier of the reservation." } } }, "content": { "type": "string", "description": "Message text content." }, "sender": { "type": "object", "properties": { "participant_id": { "type": "string", "description": "Unique identifier of the conversation participant." }, "metadata": { "type": "object", "description": "Additional metadata about the sender." } } }, "attachments": { "type": "array", "items": { "type": "string", "description": "Attachment IDs included with the message." } }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp in ISO 8601 format (UTC) when the message was sent." } } } } } } } }, "example": { "request_id": "0248d85a-17e0-44b3-a37c-7d4b5c03f58b", "data": { "messages": [ { "message_id": "daca26da-4ce3-519d-b9eb-623eeb674800", "reply_to": null, "conversation": { "id": "b2364f9b-6466-599a-a947-0d35cff4f492", "accommodation": "5589515", "reservation": "4439608993" }, "content": "Hello Anne, welcome to CS Training Test Hotel...", "sender": { "participant_id": "930d9af8-2390-5e43-a4d7-235b52a30a14", "metadata": { "type": "property", "name": "CS Training Test Hotel Sloterdijk 10" } }, "attachments": [], "timestamp": "2025-05-08T08:49:15.000Z" } ] } } } } } } } }, "/messages/latest/confirm": { "post": { "summary": "Confirm message receipt", "description": "Confirms receipt of specified messages.\nThis confirmation is required before receiving new messages from the POST /messages/latest endpoint.\n", "operationId": "confirmMessageReceipt", "tags": [ "Messages" ], "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConfirmMessageReceiptRequest", "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "string", "description": "Unique identifier of a message to confirm receipt of." } } }, "example": { "messages": [ "8586a789-44f4-5521-9f27-f5efd097cba" ] } } } } } } }, "/messages/attachments/upload": { "post": { "summary": "Upload an attachment", "description": "Uploads a file to be used as a message attachment.\nThe response includes an attachment ID to reference when sending messages.\n", "operationId": "uploadAttachment", "tags": [ "Attachments" ], "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "UploadAttachmentRequest", "type": "object", "required": [ "conversation", "accommodation", "file_size", "file_name", "file_type", "file_content" ], "properties": { "conversation": { "type": "string", "description": "Unique identifier of the conversation." }, "accommodation": { "type": "string", "description": "Unique identifier of the property." }, "file_size": { "type": "integer", "description": "Size of the file in bytes." }, "file_name": { "type": "string", "description": "Original file name including extension." }, "file_type": { "type": "string", "description": "MIME type of the file." }, "file_content": { "type": "string", "description": "Base64-encoded content of the file." } } }, "example": { "accommodation": "6819547", "conversation": "8586a789-44f4-5521-9f27-f5efd097cba6", "file_size": 17580, "file_name": "a3e062a0-3e6b-4592-9df2-64cf83688084.jpg", "file_type": "image/jpeg", "file_content": "/9j/4AAQSkZJRgABAQACWAJYAAD/2wCEAAgGBgc" } } } } } }, "/messages/attachments/download": { "post": { "summary": "Download a message attachment", "description": "Retrieves a file that was attached to a message. The response includes the file's content as a base64-encoded string.\n", "operationId": "downloadMessageAttachment", "tags": [ "Attachments" ], "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "DownloadAttachmentRequest", "type": "object", "required": [ "conversation", "accommodation", "attachment" ], "properties": { "conversation": { "type": "string", "description": "The unique identifier of the conversation that contains the attachment." }, "accommodation": { "type": "string", "description": "The unique identifier of the property where the conversation occurred." }, "attachment": { "type": "string", "description": "The unique identifier of the attachment to download." } } }, "example": { "conversation": "8586a789-44f4-5521-9f27-f5efd097cba6", "accommodation": "6819547", "attachment": "9635be40-1dc6-11f0-8893-0130f0cdef6d" } } } }, "responses": { "200": { "description": "Attachment successfully retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "A unique ID for this request. Please include this when contacting support." }, "data": { "type": "object", "properties": { "conversation": { "type": "string", "description": "The ID of the conversation the file belongs to." }, "file_content": { "type": "string", "description": "The base64-encoded content of the attachment." } } } } }, "example": { "request_id": "773e2c0d-1ab3-449b-b88a-3d6b5ce09ae7", "data": { "conversation": "8586a789-44f4-5521-9f27-f5efd097cba6", "file_content": "/9j/4AAQSkZJRgABAQACWAJYAAD/2wCEAAgGBgc..." } } } } } } } }, "/messages/attachments/metadata": { "post": { "summary": "Retrieve attachment metadata", "description": "Returns metadata for a file uploaded in a message, including its name, type, and size.\n", "operationId": "getAttachmentMetadata", "tags": [ "Attachments" ], "parameters": [ { "$ref": "#/components/parameters/AffiliateIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "AttachmentMetadataRequest", "type": "object", "required": [ "conversation", "accommodation", "attachment" ], "properties": { "conversation": { "type": "string", "description": "The unique identifier of the conversation that includes the attachment." }, "accommodation": { "type": "string", "description": "The unique identifier of the property associated with the conversation." }, "attachment": { "type": "string", "description": "The unique identifier of the attachment whose metadata is being requested." } } }, "example": { "conversation": "8586a789-44f4-5521-9f27-f5efd097cba6", "accommodation": "6819547", "attachment": "9635be40-1dc6-11f0-8893-0130f0cdef6d" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "description": "Uniquely identifies the request. Please provide this identifier when contacting support.", "type": "string" }, "data": { "type": "object", "properties": { "metadata": { "type": "object", "properties": { "file_size": { "description": "The size of the attachment (up to 1MB)", "type": "integer" }, "file_name": { "description": "Original name of the file, including extension.", "type": "string" }, "file_type": { "description": "MIME type of the file (e.g., image/jpeg).", "type": "string" } } } } } } }, "example": { "request_id": "fec1a9bb-9c85-42fc-a109-3707e1ed4de7", "data": { "metadata": { "file_name": "1ce51916-d8de-4144-a4be-265ccae5df9d.jpg", "file_type": "image/jpeg", "file_size": "92620" } } } } } } } } } } }