Product API
Getting startedProduct API

Requirements and best practices

This section highlights requirements and best practices to keep in mind when developing your Product API integration.

If you are looking for information about capabilities offered by additional APIs, such as Property API or Image API, refer to the overview page.

Development requirements

Before implementing Product API, make sure you meet these requirements:

  • Have a reliable connection to the Internet.
  • Be able to initiate HTTPS connections to Expedia Group servers and provide authentication (username/password)
  • Expedia Group will only accept request sent using TLS v1.2 protocol.
  • Be able to connect using the provided Expedia Group URL. Expedia Group does not support connection to the API directly via IP address, as this address is subject to change without notice.
    • If you prefer IP addresses for communication performance reasons, you may consider implementing an address caching strategy to reduce DNS lookups for the URLs.
    • If you whitelist outbound connections, you must do so using a URL pattern rather than an IP range, as Expedia Group cannot guarantee a specific IP range/subnet.
  • Be able to generate JSON documents for read, create, and update requests, and accept JSON payloads for create and update requests.
  • Use Availability and Rates (AR) API to send XML updates about inventory availability.
  • Use either Booking Retrieval and Booking Confirmation APIs or Booking Notification API to
    • Be able to retrieve or receive bookings (reservations, modifications and cancellations) using XML messages
    • Be able to provide confirmation numbers for bookings (reservations, modifications, and cancellations) using XML messages
    • Be able to troubleshoot errors and warning scenarios according to this specification’s recommendations
  • Abide by Expedia Group’s terms and conditions

JSON requirements

The service will return JSON documents for read, create, and update requests, and accept JSON payloads for create and update requests.

In addition:

  • Entity - All successful responses returned by Expedia Group services are encapsulated within an HTTP entity. Entities are used to make successful responses generic across different resources and operations. The Entity element may represent a single object, or multiple objects. When referring to multiple objects, it is called an array.
  • Errors - If a request produces one or more errors, the response will return an array of one or more errors. If errors are present, Entity will not be present.
  • MUST-IGNORE - The service is constantly evolving and you should utilize a must-ignore policy. If Product API starts returning additional data elements in responses, you should ignore the data elements you do not need. Note that you should also be able to serve the additional data back in an update request, as our update requests are full overlay, and failure to provide additional data back in update requests could cause data to be removed.

Security requirements

Product API uses secure endpoints provided by Expedia Group, https://services.expediapartnercentral.com/. For a complete list of endpoints for different functions within Product API, see the table in Resources and endpoints overview.

Here are the general guidelines for Product API integration:

  • Our API only supports HTTP 1.1. Requests made with HTTP 1.0 explicitly will be denied.
  • TLS 1.2 is required.SSL has been deprecated as a supported protocol and its use is not permitted with integrations to Expedia Group systems. Instead, use TLS to provide over-the-wire encryption (HTTPS). Note that Expedia Group’s servers are not configured to accept posts over unsecured HTTP.
  • Be secured using basic authentication
Note: Anyone with development questions or that has not worked with Expedia Group before should contact us.

Minimum certification requirements

Partners who want to adopt Product API are required to successfully complete end-to-end certification with Expedia Group teams. Specifically, the partner must be able to

  • Read (GET) data for single and/or multiple Room Types.
  • Read (GET) data for single and/or multiple Rate Plans.
  • Create (POST) single Room Type and Rate Plan.
  • Update/modify Room Type and Rate Plan via full overlay (PUT) and/or partial update (PATCH).
  • Set Rate Plan Status to inactive via PUT and/or PATCH or able to remove (DELETE) Rate Plans (this is not required for Vacation Rental Providers using Key Level Units/Single Rate Plan configuration; please discuss any questions with your Technical Relationship Manager.)

Best practices

When designing the electronic interface used to connect to Expedia Group servers to read, create, and update room types and rate plans, make sure to read and understand the following guidelines, recommendations and best practices.

DO:

  • Use Expedia Group room and rate plan IDs to identify correct rooms and rate plans to be updated. Ensure the correct Expedia Group room and rate IDs are accurately mapped in your implementation of Product API to make sure the right rooms and/or rate plans are updated when the API sends updates.
  • Use caution when sequencing messages to Expedia Group - sending an older message after a newer message can overwrite current information with out-dated data.
  • Ensure monitoring is in place in the Product API implementation to validate the success rate of updates, including visibility in error details/messaging.
  • Ensure error reports are reviewed and actioned by the appropriate team.

DON’T:

  • Send create or update messages with the partner code in the URL
  • Attempt to create duplicates (rooms or rates with the already used codes)
  • Attempt to convert the pricing model of the active rates.
  • Map the same value add inclusion on the room type and/or rate plan level
  • Attempt to modify property level amenities with Product API
  • When performing updates, do not send concurrent messages for the same entity (room type or rate plan), i.e. messages within milliseconds of the previous update.
  • Ignore any errors that might be received. These may signal connection issues or problems with your request.

Alarms and monitoring

Ensure monitoring is in place for the API implementation to get detailed information on any errors. Alarms should also be created to notify you when the rate of message errors returned by Expedia Group exceeds an acceptable threshold. Review errors frequently to ensure that room types and rate plans are correct, and that all updates are processed accurately. Failure to do so may result in Expedia Group customers booking incorrect room types or rate plans.

Simplified mapping process with Product API

In the past, a sometimes lengthy series of manual processes had to be completed prior to being able to send inventory and rates information. With Product API, these manual steps are eliminated.

Once the room types and rate plans are defined and exist in the connectivity system, Product API just needs to be called to create the room types and rate plans. In the responses returned by the API, the IDs required for mapping are included. The system will know right away which IDs should subsequently be used and should be able to map them automatically, using the Product API response.

product api updated eg documentation image8

Property read function

The property read function allows for the retrieval of several important settings related to properties’ configuration in Expedia Group’s system. Some of these settings will help you better understand how to manage room type and rate plan resources.

It also enables you to find out which properties are currently assigned to your accounts, by simply calling the /properties endpoint and iterating through all the properties returned.

Detailed examples of both Single property read and Multiple properties read can be found in the Property read function section of the Sample messages.

Getting active or all resources when calling a list endpoint

By default, when one of the list endpoints (properties, room types, or rate plans) is called, only active resources are returned. To get all resources including ones that might not be active at the moment, an optional status parameter can be added, with value all. Example for the properties list:

/products/properties?status=all

This becomes important when creating new room types. By default, room types are created as inactive in Expedia Group’s system, and will only become active once the first active rate plan is added. Therefore, if a room type is successfully created, and then an attempt to call the /roomTypes endpoint with no parameters is sent, the the room type will not be received back in the response, unless ?status=all is added:

/properties/123/roomTypes?status=all

Room type resources

The room type resource describes the configuration of a specific room type/category/class in the Expedia Group system. Room types belong to properties, and each room type contains one or more rate plans. A room type resource contains information such as bed types, smoking preferences, occupancy settings by age categories, etc.

Against the room type resource, a list of room types or a specific room type can be retrieved. New room types can be created (one at a time), an existing room type can be edited (one at a time, with a full overlay operation), or existing room types can be edited (one at a time) with a partial overlay using the PATCH command.

Examples to read single or multiple room type resources, create room types, and modify room types can be found in the Examples section under Room type resources.

Note: Property inventory can be updated with theAvailability and Rates (AR) API. Various fees collected on-site can be added or updated with Partner Central or Property API as well.

Rate plans are a set of attributes that describe the pricing information of a room type. They consist of the room’s rate and its policies (e.g. fees, cancellation penalties, length-of stay, and advance purchase options). Be aware that room types can have multiple rate plans, but each rate plan ID can only belong to one room type. Also note that for properties using the Expedia Traveler Preference (ETP) business model, Standalone rates will have two IDs - one for Expedia Collect and one for Hotel Collect. Hotel Collect rate plans always have an "A" at the end of the rate plan ID.

Mapping between properties’ room and rate codes and Expedia Group’s equivalent room type and rate plan IDs must be developed and maintained. This mapping is critical for sending updates because the Expedia ID must be specified in the JSON scripts, not the property’s codes.

Example: In the property’s system, room type code STD maps to a rate plan code BPK. This product is mapped on Expedia Group as room type ID 123 and unique rate plan 1093294 in Expedia Group’s system. The link between room type STD/123 and rate plan BPK/1093294 should be preserved in your system.

Whenever properties change their room or rate codes, or request new products to be created, the mapping of the property’s codes must be updated in its system with Expedia Group’s equivalent new or existing IDs to maintain successful communication of availability updates and booking notifications between you and Expedia Group.

The Expedia Group room type and rate plan IDs are alpha-numeric, and the relationship between room type and rate plan is a one to many hierarchy.

Note: Expedia IDs are also used to identify the room type and rate plan of a booking in any emailed notifications sent to the property.

Code to the correct pricing model

When developing for Product API, make sure you develop the correct pricing models for your customers. Currently Expedia offers several different pricing models: occupancy-based pricing (OBP), per-day pricing (PDP), day-of-arrival pricing (DOA), and per-day length-of-stay pricing (LOS).

For more details, see Pricing models explained.

Use the correct modify function: partial or full overlay

Expedia Group offers 2 different methods to make changes to products: PUT or PATCH. This guide intends to give an overview of both options. Anyone interested in learning more should refer to the Modify an existing room type section.

Note: If unsure of which operation to use, always favor the PATCH (partial) update feature.
Modifying with PUT

The PUT modify operation is a full overlay. The payload of the modify request needs to include all the elements/attributes returned by read (GET) of this resource (with the exception of the entity element). In the context of a room type modify using the PUT operation, if one of the values in elements such as bed types or age categories are removed, the system interprets this as the user removing that category from the room type.

When making use of the PUT method, a GET request must first be issued to read the resource, and then what needs to be changed can be edited. Once done, the whole payload is resubmitted with the changes. Issuing a GET first, before making any modification, is quite important as changes to resources can be made via other means. For example, property managers or Expedia Group Market Managers can make changes with Partner Central. To find out the latest state of the resource, it is best to do a GET first before making any changes to it.

Example: If the GET request returns the following information for ageCategories (Adult, ChildAgeA, and Infant):

1"ageCategories": [
2 {
3 "category": "Adult",
4 "minAge": 18
5 },
6 {
7 "category": "ChildAgeA",
8 "minAge": 5
9 },
10 {
11 "category": "Infant",
12 "minAge": 3
13 }
14]

And the PUT statement includes only the following ageCategories (Adult and ChildAgeA):

1"ageCategories": [
2 {
3 "category": "Adult",
4 "minAge": 18
5 },
6 {
7 "category": "ChildAgeA",
8 "minAge": 5
9 }
10]

The system assumes ageCategories "Infant" no longer applies and removes it because it is not defined in the PUT request.

For the most part, the same objects that are manageable in the create operation can be modified as well. In the context of the room type, it is true for most objects/elements. In the context of a rate plan, however, some things cannot be changed after creation, like the distribution and pricing models for example.

Modifying with PATCH

The PATCH modify operation is a way to send only what needs to be modified on a resource.

Expedia Group implemented the Merge-PATCH strategy. Any of the top level elements that need to be modified can be submitted, and the ones that do not need to change can be omitted. Expedia Group will take care of merging the resource updates and preserve what was not included at the resource's top level.

It is important to note that any top level object is treated as a full overlay even when using Merge-PATCH. For example, if the cancelPolicy object is included, all the elements/values of that object need to be included as this specific object update will be treated as a full overlay.

Send the right type of rate to Expedia: sell rate, net rate or lowest available rate

Expedia Group accepts receiving sell rate, net rate, or lowest available rate (LAR or Sell LAR) for rate updates. Rate Acquisition Type settings are confirmed at the property level and cannot be modified with Product API. Visit the Inventory section under the Availability and Rates APIto learn more about the type of rate to send to Expedia Group. The rates sent must be in sync with the configuration in Expedia Group’s system. Please verify which type of rate is being used with the GET call for the property when using Property API.

Room types and rate plans available for properties using the Expedia Traveler Preference business model are available to travelers with both the "pay now" at the time of booking (EC) and "pay later" at the hotel (HC) options.

Identifying Expedia Traveler Preference properties

To identify whether a property has Expedia Traveler Preference enabled, the property resource will return an array of 2 distributionModels, Expedia Collect and Hotel Collect:

1"distributionModels": [
2 "ExpediaCollect",
3 "HotelCollect"
4],
Identifying Expedia Traveler Preference rate plans

When properties opt into the program, all their standalone rate plans must be enabled for the Expedia Traveler Preference program. This translates into having 2 different distribution rules configured for each rate plan. For example, when doing a GET on a rate plan enabled for the program, something like this would be returned:

1{
2 "entity": {
3 "resourceId": 200086494,
4 ...
5 "distributionRules": [
6 {
7 "expediaId": "200086494",
8 "partnerCode": "ABC123",
9 "distributionModel": "ExpediaCollect",
10 "manageable": true,
11 "compensation": {
12 "percent": 0.15,
13 "minAmount": 20
14 }
15 },
16 {
17 "expediaId": "200086494A",
18 "partnerCode": "DEF123",
19 "distributionModel": "HotelCollect",
20 "manageable": false,
21 "compensation": {
22 "percent": 0.18
23 }
24 }
25 ]
26 ...
27 }
28}
Creating Expedia Traveler Preference rate plans

When a property opts into the program, all its standalone rate plans must be enabled for Expedia Traveler Preference (ETP). The minimum information needed to create an Expedia Traveler Preference-enabled rate plan is 2 distribution rules, along with a partner code for each. The partner code doesn't have to be different between the Expedia Collect and Hotel Collect rules, but it has to be unique across all the rate plans under the room type it belongs to.

Example:

1{
2 "distributionRules": [
3 {
4 "partnerCode": "A123",
5 "distributionModel": "ExpediaCollect"
6 },
7 {
8 "partnerCode": "D123",
9 "distributionModel": "HotelCollect"
10 }
11 ]
12}

This will create a rate plan with these 2 codes, and will default everything else.

What if a system requires two distinct rate plans to support Expedia Traveler Preference?

If two distinct rate plans are used to support the Expedia Traveler Preference program, these will need to be combined into one rate plan creation request to Expedia Group. The codes for their Expedia Collect and Hotel Collect versions should be provided under the appropriate distribution rules. Then Expedia Group’s response is consumed and the returned Expedia rate plan IDs are mapped and returned (i.e. resource ID) as part of each distribution rule. These IDs will also be used to interpret booking messages or push availability/rate messages to Expedia Group.

Room name logic

When naming room types with the room type resource, the name is provided in one of two ways:

  • Use one of the predefined room names
  • Build a name from room-level attributes

Expedia Group is unable to accept free text room names from its partners. Because Expedia Group has points of sale in more than 45 languages, and wants to offer the best experience to all its customers around the world, names must be received in a structured way, to enable instant availability in all languages.

Using predefined names

When using a predefined room name, creating a room type is very straightforward. When it comes to providing the name, all that must be done is to submit one of these predefined names under the "value" element:

1{
2 ...
3 "name": {
4 "value": "Junior Suite"
5 }
6 ...
7}

For more details, see the table of Available predefined room names.

Using room name attributes

To convey more information about a room with its room name, Expedia Group offers the possibility to build a name from structured attributes. There are up to 10 different attributes that can be used to build a name. However, because Expedia Group also has a constraint on room name length, not all 10 attributes can be used all at once.

Expedia Group recommends that all the attributes that a property would like to be part of the name be provided. Expedia Group will then only use the ones deemed most relevant if too many attributes are received.

Example with all attributes selected:

1{
2 ...
3 "name": {
4 "attributes": {
5 "typeOfRoom": "Studio",
6 "roomClass": "Basic",
7 "includeBedType": true,
8 "bedroomDetails": "1 Bedroom",
9 "includeSmokingPref": true,
10 "accessibility": true,
11 "view": "Beach View",
12 "featuredAmenity": "Hot Tub",
13 "area": "Corner",
14 "customLabel": "Blue Room"
15 }
16 }
17 ...
18}

If more control over room names and which attributes get used is desired, refer to the table below indicating Expedia Group’s sets and the maximum number of attributes Expedia Group will use from each group.

Attribute name

Group

Optional

Explanation

typeOfRoom

-

No

Required and always used.

roomClass

-

Yes

Always used in name if provided.

includeBedType

Bedding

Yes

Part of a grouping of 2 elements. Only one of the two will be used if both are specified in this group.

If the room type includes a vast array of bedding options (e.g. King, Queen, Twin and Sofa), Expedia Group defaults to "Multiple Beds" instead of listing each bed type in the room name, as it would exceed 100 character limitation.

bedroomDetails

Bedding

Yes

Part of a grouping of 2 elements. Only one of the two will be used if both are specified in this group.

includeSmokingPref

Key Features

Yes

Part of a grouping of 5 elements. Expedia Group will use a maximum of 2 attributes from this group.

accessibility

Key Features

Yes

Part of a grouping of 5 elements. Expedia Group will use a maximum of 2 attributes from this group. Indicates if the room is accessible to wheelchairs.

view

Key Features

Yes

Part of a grouping of 5 elements. Expedia Group will use a maximum of 2 attributes from this group.

featuredAmenity

Key Features

Yes

Part of a grouping of 5 elements. Expedia Group will use a maximum of 2 attributes from this group.

area

Key Features

Yes

Part of a grouping of 5 elements. Expedia Group will use a maximum of 2 attributes from this group.

customLabel

-

Yes

Always used in name if provided.

Data type: string, 1-37 characters

For more information about the various possible values and constraints on each of these attributes, please refer to the Room Name Attributes table.

Cancellation and change policy

The Cancellation and Change Policy is applicable when a guest wants to cancel a reservation or change a reservation that would cause the total amount of the initial reservation to be different from the total amount for the modified reservation. Changes impacting the reservation rate include: a change of room type, rate plan, occupancy or dates. See the CancelPolicy table for more detailed information.

Cancellation policy logic takes into account:

  1. Cancellation window or cancellation policy level, determined by the "deadline" attributes
  2. Cancellation window penalties (cancellation policy level) starting with the window where the "deadline" is set to 0, up to three windows.
  3. Cancellation time (property level)

The logic is:

  • Cancellation time at the property level determines at what time the cancellation window ends in hours.
  • Cancellation window is counted from the date of the arrival backwards
  • Depending on when the cancellation was performed, the applicable window applies.

Cancellation and change policies are optional when creating a new rate plan.

  • If provided, it is required to provide at least one defaultPenalty with one deadline in hours, and a penalty.
  • If no cancellation policy is provided in a create rate plan request, Expedia Group will try to select one which already exists, is refundable, and was most recently used by an active rate plan of the same type (standalone, package or corporate).
  • If no cancellation policy can be found due to not having any active rate plans of the required type, we will default to a standard cancellation policy where the cancellation deadline is set to 24 hours from guest arrival, the penalty for cancelling inside this deadline is one night room and tax, and there is no penalty for cancelling outside of this deadline.

When providing a cancellation policy, one to three defaultPenalties objects can be provided.

  • At least one defaultPenalty must be provided, with a deadline set to 0. This will determine the inside window penalty.
  • If no other default penalty is provided, there will be a single strategy applied, defined by that defaultPenalty per stay fee and amount. This means that the same penalty applies regardless of the cancellation time or window.
  • In addition to the default penalty with a deadline set at 0, up to two additional defaultPenalties can be provided (for a total of 3).
  • If a second and third penalty is provided, its deadline must be greater than 0, and less than 1000. This determines the window penalties.
  • It is currently not possible to provide more than 3 defaultPenalties. Expedia can only manage 3 different penalties per cancellation & change policy.

Optionally, exceptions objects can be added.

  • startDate and endDate are both required.
  • Exceptions with end dates in the past in a create or update message will not be accepted. Exceptions with end dates in the past will not be returned in GET responses.
  • Exception date ranges cannot overlap. If more than one exception is provided, Expedia Group will make sure that there are no date overlaps between the two exception objects.
  • The rules and validations around the penalties included in an exception are the same as with the defaultPenalties object (minimum 1, maximum 3 deadlines, deadline 0 required, etc.).

When exceptions are defined, Expedia Group will apply a cancellation policy to a booking based on the booking start/arrival date. See example 1 below for a concrete example of what this means.

Example 1 - Assume a cancellation policy with only one exception defined:

  • By default, if a guest cancels 72 hours or less before a property's cancellation time, the customer pays the full amount of the reservation. If the guest cancels more than 72 hours before the property's cancellation time, the customer pays no penalty.
  • For dates from June 2nd to July 15th inclusively, the rate plan is not refundable.

To reflect such terms, the following should be sent:

1{
2 "cancelPolicy": {
3 "defaultPenalties": [
4 {
5 "deadline": 0,
6 "perStayFee": "FullCostOfStay",
7 "amount": 0
8 },
9 {
10 "deadline": 72,
11 "perStayFee": "None",
12 "amount": 0
13 }
14 ],
15 "exceptions": [
16 {
17 "startDate": "2016-06-02",
18 "endDate": "2016-07-15",
19 "penalties": [
20 {
21 "deadline": 0,
22 "perStayFee": "FullCostOfStay",
23 "amount": 0
24 }
25 ]
26 }
27 ]
28 }
29}

How will Expedia Group decide which penalty to apply to a booking based on example 1's policy?

Expedia Group picks a cancellation policy to apply based on arrival date.

Example:

  • Assume a booking is made for arrival on June 1st, for 3 nights: because the arrival date is outside of the range of dates covered by the exception, the default policy applies.
  • Assume a booking is made for arrival on July 15th, for 3 nights: because the arrival date falls on the last date of the exception, the exception policy applies.

Example 2 - Consider the following policy:

  • If a customer cancels between 24 hours or less before the property's cancellation time, the customer pays twenty percent cost of stay.
  • If a customer cancels between 24 and 72 hours before the property's cancellation time, the customer pays ten percent cost of stay.
  • If a customer cancels more than 72 hours before the property's cancellation time, the customer pays no penalty.

To reflect such terms, the following should be sent:

1{
2 "cancelPolicy": {
3 "defaultPenalties": [
4 {
5 "deadline": 0,
6 "perStayFee": "20PercentCostOfStay",
7 "amount": 0.0
8 },
9 {
10 "deadline": 24,
11 "perStayFee": "10PercentCostOfStay",
12 "amount": 0.0
13 },
14 {
15 "deadline": 72,
16 "perStayFee": "None",
17 "amount": 0.0
18 }
19 ]
20 }
21}

Example 3:

  • Cancellations within 24 hours of the property’s cancellation time deadline should be charged 1 night room and tax
  • Cancellations further out should incur a 5 units of currency penalty (for example 5 GBP for a London, UK property, assuming property rate acquisition type is Sell lowest available rate (LAR))

To reflect such terms, the following should be sent:

1"cancelPolicy": {
2 "defaultPenalties": [
3 {
4 "deadline": 0,
5 "perStayFee": "1stNightRoomAndTax",
6 "amount": 0.0
7 },
8 {
9 "deadline": 24,
10 "perStayFee": "None",
11 "amount": 5.0
12 }
13 ]
14}

Example 4 - if a policy is non-refundable, the following should be sent:

1"cancelPolicy": {
2 "defaultPenalties": [
3 {
4 "deadline": 0,
5 "perStayFee": "FullCostOfStay",
6 "amount": 0.0
7 }
8 ]
9}

Occupancy and age category settings in the room type resource

Age categories are used for two different things in Expedia Group’s system: to confirm if the room supports both adults and children, and to define additional guest amounts per age category. Extra person fees are always defined at the rate plan level.

Occupancy settings define the maximum occupancy of the room by number of adults, children, and total. Unlike the age categories, there's no granularity in the configuration for children. There is however a relationship between the age categories and the occupancy settings. If a room accepts children in its occupancy, and you want to define a maximum number of children under the occupancy element, Expedia Group will expect that the age categories include at least one ChildAge category, or Infant. If it is not the case, Expedia Group will reject the message.

Note: At properties with occupancy-based pricing, children can be charged as either regular occupants or as "Always Extra." In this case, even when children are within the maximum occupancy, pricing for each child occupant is based on the "additionalGuestAmounts" array set for each Child Age group.

The maximum number of Child Age categories supported by the property is set at the property level and cannot be overridden by Product API. Perform a GET call for the property-level information to learn which age categories are allowed (array in the attribute "allowedAgeCategories"). If this limit needs to be increased, please contact Expedia Group.

When a room supports children and infants, assuming a room can accommodate up to 4 people, Expedia Group would expect to receive a configuration similar to this:

1{
2 "ageCategories": [
3 {
4 "category": "Adult",
5 "minAge": 18
6 },
7 {
8 "category": "ChildAgeA",
9 "minAge": 0
10 }
11 ],
12 "maxOccupancy": {
13 "total": 4,
14 "adults": 4,
15 "children": 3
16 }
17}

If a room doesn't support children, Expedia Group would expect to receive something like this:

1{
2 "ageCategories": [
3 {
4 "category": "Adult",
5 "minAge": 18
6 }
7 ],
8 "maxOccupancy": {
9 "total": 4,
10 "adults": 4
11 }
12}

If a room supports children, but only older children (for example 16+), Expedia Group would expect to receive something like this:

1{
2 "ageCategories": [
3 {
4 "category": "Adult",
5 "minAge": 18
6 },
7 {
8 "category": "ChildAgeA",
9 "minAge": 16
10 }
11 ],
12 "maxOccupancy": {
13 "total": 4,
14 "adults": 4,
15 "children": 3
16 }
17}

If intending to charge children as adults and only accept older children of 16+, you could consider doing something like this as well:

1{
2 "ageCategories": [
3 {
4 "category": "Adult",
5 "minAge": 16
6 }
7 ],
8 "maxOccupancy": {
9 "total": 4,
10 "adults": 4
11 }
12}
Should the age for the Infant age category be defined if the room doesn't support infants?

Infant category definitions should never be sent to Expedia Group if the room doesn't support infants. Due to the way occupancy is calculated, there is only one count for any non-adult age category: the children count. It is not possible to send a count of 0 infants. For that reason, it is critical that properties that cannot take infants in their rooms do not define the infant age category at all.

As a best practice, only define the guest age categories supported. The examples defined in the Occupancy and age category section were designed with this principle in mind.

Can a room be defined where only Infants and Adults are accepted (no children)?

Expedia Group does not support defining room configurations where infants are allowed, but other children are not accepted.

It is also important to know that there is no "maximum age" explicitly defined for an age category. The maximum age of a given category is equivalent to the (minimum age-1) of the next defined category.

If something like this was sent:

1{
2 "ageCategories": [
3 {
4 "category": "Adult",
5 "minAge": 18
6 },
7 {
8 "category": "Infant",
9 "minAge": 0
10 }
11 ],
12 "maxOccupancy": {
13 "total": 3,
14 "adults": 2,
15 "children": 1
16 }
17}

The outcome of this request would be that any guest aged from 0 to 17 would be considered an Infant, and anyone 18 or above would be considered an adult.

Can a room accept children without an additional fee?

Yes, if a property has occupancy-based pricing and the child pricing logic is set to consider children always as extra occupants. The room type will have to be mapped to include at least ChildAgeA. Then the rate plan must be mapped with no additional charge for the children.

For instance, in the room:

1"ageCategories": [
2 {
3 "category": "Adult",
4 "minAge": 18
5 },
6 {
7 "category": "ChildAgeA",
8 "minAge": 5
9 },
10 {
11 "category": "ChildAgeB",
12 "minAge": 0
13 }
14]

The rate carries:

1"additionalGuestAmounts": [
2 {
3 "ageCategory": "Adult",
4 "amount": 50
5 },
6 {
7 "ageCategory": "ChildAgeA",
8 "amount": 50
9 }
10]

Therefore, children ages 0 to 5 will not be charged.

Use Product API to update rate plans requiring deposits

With the introduction of theDeposit API, some might be interested in managing only the depositRequired flag of rate plans, in order to indicate which rate plans should make use of a deposit policy. If you know which rate plans (and corresponding room type IDs) should make use of the policy, they can be PATCHed with the following operation:

PATCH https://services.expediapartnercentral.com/properties/{Expedia Property ID}/roomTypes/{room type ID of the rate plan to be patched}/ratePlans/{rate plan ID to be update}

Content-Type: application/vnd.expedia.eps.product-v3+json

1{
2 "depositRequired": true
3}

The same operation needs to be repeated for all rate plans requiring a deposit.

If you don't know the room type or rate plan IDs, they can be discovered by using GET roomTypes and GET ratePlans calls.

Example - to list all room types of a property:

GET https://services.expediapartnercentral.com/properties/{Expedia Property ID}/roomTypes

This will give back a list of active roomTypes. A query parameter (?status=all) could be added to return all room types, both active and inactive. This shouldn't be needed since inactive room types wouldn't be available to guests, therefore updating the depositRequired flag would have no visible effect for them.

Then, to get the rate plans, you can iterate on each room type, and request all rate plans for each room type, using:

GET https://services.expediapartnercentral.com/properties/{Expedia Property ID}/roomTypes/{Expedia room type ID}/ratePlans

This will give back a list of active rate plans. A query parameter (?status=all) could be added to return both active and inactive rate plans.

Once all room types and rate plans have been identified, and the deposit policy has been created with Deposit API, those rate plans requiring a deposit can be updated with the same PATCH call as above.

Note: It is important to know that only Hotel Collect or Expedia Traveler Preference (Hotel Collect/Expedia Collect) rate plans can be updated to require a deposit.