Requirements and best practicesCopy link

This section highlights requirements and best practices to keep in mind when developing your Deposit 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 Deposit 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.
• Be able to generate JSON documents for read, create, and update requests, and accept JSON payloads for create and update requests.
• Use either 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
• Use Product API to enable the deposit policy on specific rate plans
• 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 Deposit API starts returning additional data elements in responses, you should ignore the data elements you do not need.

Security requirements

Deposit API uses secure endpoints provided by Expedia Group, https://services.expediapartnercentral.com/. For a complete list of endpoints for different functions within Deposit API, see Requests.

Here are the general guidelines for Deposit API integration:

• HTTP 1.1 - Our API only supports HTTP 1.1. Requests made with HTTP 1.0 explicitly will be denied.

• TLS 1.2 - 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.

• Authentication - Be secured using basic authentication. Note that anyone with development questions or that has not worked with Expedia Group before should contact us.

Minimum certification requirements

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

• Create a deposit policy at the property level
• Read and update deposits
• Delete existing deposits

Best practices

In general, keep the following best practices in mind:

• Unique IDs - The property ID is defined by Expedia Group and uniquely identifies a property in the Expedia Group system. You map it to the code in your system. Property IDs are referred to in the endpoint URL.
• Use Product API to attach deposit policy to rate plans
  • Once a policy exists, it is important to indicate which rate plans should make use of it. By default, when a policy is added for the first time, no rate plan will be defined to use it.
  • To indicate which rate plans should make use of the new deposit policy, you can use either Partner Central and manually enable rate plans, or use Product API to update any rate plan that requires a deposit. In Product API, the PATCH operation can be used to update the depositRequired flag on the rate plan resource.
• Do not use Partner Central to update deposit policy information

To avoid concurrent, conflicting updates, Expedia Group encourages you to avoid mixing Deposit API usage with managing deposit policy information in Partner Central. Deposit policies created with Partner Central can be edited with Deposit API. The opposite is also true, it is possible to edit a deposit policy created in Deposit API with Partner Central. However, if both methods are actively being used to update deposit policies, conflicting updates may occur.

Alarms and monitoring

You should ensure monitoring is in place for your interface implementation so the ratio of successful Deposit API updates is visible and you can 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. It is recommended that an alarm be triggered when any type of message returns errors at a rate of 10% or more. You should review errors frequently to ensure that all updates are processed correctly.

Do not ignore any errors that might be received. These may signal connection issues or problems with your request.

Deposit policy contents

A deposit policy is formed of up to 2 components: a default policy, and up to 4 exception policies. It is possible to only have a default policy, or to only have exceptions.

Within a policy, between 1 and 4 payment installments can be defined. It is possible to define timing of these installments as: time of booking, days prior to check-in, or time of check-in.

The amounts to pay can be either fixed amounts, % of the total booking value, or a certain number of nights.

Example: A property who would like to collect 10% of the booking value at time of booking, and the remainder at time of check-in:

1{
2  "defaultPolicy": {
3    "payments": [
4      {
5        "type": "PERCENT",
6        "value": 10,
7        "when": {
8          "type": "UPON_BOOKING"
9        }
10      },
11      {
12        "type": "REMAINDER",
13        "when": {
14          "type": "UPON_ARRIVAL"
15        }
16      }
17    ]
18  }
19}

When the policy is an exception, a start date, end date and applicable days of week need to be defined as part of the exception. Up to 15 different date ranges can be specified with any given exception. For example, if a property wants to set a policy where there is only an exception specifying that for the month of August 2020, the full payment needs to be made at the time of booking:

1{
2  "exceptionPolicies": [
3    {
4      "dateRanges": [
5        {
6          "startDate": "2020-07-30",
7          "endDate": "2020-08-30",
8          "daysOfWeek": [
9            "SUN",
10            "MON",
11            "TUE",
12            "WED",
13            "THU",
14            "FRI",
15            "SAT"
16          ]
17        }
18      ],
19      "description": "High Season",
20      "payments": [
21        {
22          "type": "PERCENT",
23          "value": 100,
24          "when": {
25            "type": "UPON_BOOKING"
26          }
27        }
28      ]
29    }
30  ]
31}

When there are multiple exceptions specified, the order in which they are specified in the JSON array matters. Expedia Group allows you to have some overlap in dates between exceptions. In case of overlap, position 0 in the array will always take precedence over position 1, etc.

Example:

1{
2  "exceptionPolicies": [
3    {
4      "dateRanges": [
5        {
6          "startDate": "2020-05-01",
7          "endDate": "2020-07-15",
8          "daysOfWeek": [
9            "SUN",
10            "MON",
11            "TUE",
12            "WED",
13            "THU",
14            "FRI",
15            "SAT"
16          ]
17        }
18      ],
19      "description": "Mid Season",
20      "payments": [
21        {
22          "type": "PERCENT",
23          "value": 50,
24          "when": {
25            "type": "UPON_BOOKING"
26          }
27        },
28        {
29          "type": "PERCENT",
30          "value": 25,
31          "when": {
32            "type": "DAYS_PRIOR",
33            "value": 15
34          }
35        },
36        {
37          "type": "REMAINDER",
38          "when": {
39            "type": "UPON_ARRIVAL"
40          }
41        }
42      ]
43    },
44    {
45      "dateRanges": [
46        {
47          "startDate": "2020-07-01",
48          "endDate": "2020-08-30",
49          "daysOfWeek": [
50            "SUN",
51            "MON",
52            "TUE",
53            "WED",
54            "THU",
55            "FRI",
56            "SAT"
57          ]
58        }
59      ],
60      "description": "High Season",
61      "payments": [
62        {
63          "type": "PERCENT",
64          "value": 100,
65          "when": {
66            "type": "UPON_BOOKING"
67          }
68        }
69      ]
70    }
71  ]
72}

In the above example, both exceptions cover the dates from 2020-07-01 to 2020-07-15. Expedia Group will always start from the array position 0, and look for a match. If one is found, we stop looking. In the above example, if someone was looking to stay on July 1st, it would be the first exception in the array, the one with the description "Mid Season", that would apply.

Logic for selecting deposit policy

When a customer selects dates that span across a default policy and one or more exceptions, Expedia Group will use the policy exception in ascending order (0..3) from the array.

For example, assume this deposit policy is defined for the property:

1{
2  "defaultPolicy": {
3    "payments": [
4      {
5        "type": "AMOUNT",
6        "value": 50,
7        "when": {
8          "type": "UPON_BOOKING"
9        }
10      },
11      {
12        "type": "REMAINDER",
13        "when": {
14          "type": "UPON_ARRIVAL"
15        }
16      }
17    ]
18  },
19  "exceptionPolicies": [
20    {
21      "dateRanges": [
22        {
23          "startDate": "2020-05-01",
24          "endDate": "2020-05-02",
25          "daysOfWeek": [
26            "SUN",
27            "MON",
28            "TUE",
29            "WED",
30            "THU",
31            "FRI",
32            "SAT"
33          ]
34        }
35      ],
36      "description": "Exception at position 0",
37      "payments": [
38        {
39          "type": "PERCENT",
40          "value": 100,
41          "when": {
42            "type": "UPON_BOOKING"
43          }
44        }
45      ]
46    },
47    {
48      "dateRanges": [
49        {
50          "startDate": "2020-05-02",
51          "endDate": "2020-05-04",
52          "daysOfWeek": [
53            "SUN",
54            "MON",
55            "TUE",
56            "WED",
57            "THU",
58            "FRI",
59            "SAT"
60          ]
61        }
62      ],
63      "description": "Exception at position 1",
64      "payments": [
65        {
66          "type": "PERCENT",
67          "value": 50,
68          "when": {
69            "type": "UPON_BOOKING"
70          }
71        }
72      ]
73    }
74  ]
75}

If a customer books a stay between April 28 and May 02 (staying the nights of April 28, 29, 30 and May 1), Expedia Group will select the exception policy at position 0 in the array.

If a customer booked a slightly longer stay spanning across the default policy and the 2 exceptions, for example from April 28 to May 10, it would again be the exception at position 0 in the json exception policies array that would be selected.

Logic for when exception dates and day-of-week data do not overlap

Expedia Group does not confirm whether or not the date range and the days of the week specified intersect. Therefore, Expedia Group would accept setting an exception like this:

1{
2  "exceptionPolicies": [
3    {
4      "dateRanges": [
5        {
6          "startDate": "2020-05-01",
7          "endDate": "2020-05-02",
8          "daysOfWeek": [
9            "MON",
10            "TUE"
11          ]
12        }
13      ],
14      "description": "Exception at position 0",
15      "payments": [
16        {
17          "type": "PERCENT",
18          "value": 100,
19          "when": {
20            "type": "UPON_BOOKING"
21          }
22        }
23      ]
24    }
25  ]
26}

However, this would never be applied because May 1st and 2nd are a Friday and Saturday respectively, and the dayOfWeek array only contains Monday and Tuesdays effective dates.

Use Product API to update rate plans requiring deposits

Once a policy exists, it is important to indicate which rate plans should make use of it. By default, when a policy is added for the first time, no rate plan will be defined to use one.

To indicate which rate plans should make use of the new deposit policy, you can use either Partner Central and manually enable rate plans, or use Product API to update any rate plan that requires a deposit. In Product API, the PATCH operation can be used to update the depositRequired flag on the rate plan resource.

Deposit policies are configured by property, not by rate plan

It is not possible to have different deposit policies for different rate plans. The deposit policy is configured at the property level, and will apply to any rate plan enabled to use it.

Deposit policies are different from cancellation policies

In the Expedia Group system, deposit and cancel policies are very different. For a Hotel Collect booking, if the property wants to charge anything before the guest checks in at the property, a deposit policy must be defined and have rate plans enabled to use the policy.

For example, assume a property defined a cancellation policy stating that the rate is non-refundable 7 days prior to check-in. If the property plans to charge the full amount of the reservation 7 days prior to check-in, a deposit policy needs to be defined, indicating that the full amount of the reservation will be charged 7 days prior to check-in.