ReferenceDeposit API

Requests

Deposit API requests are initiated by the partner and use the RESTful method to send the request to the endpoint.

Expedia Group’s APIs live under the https://services.expediapartnercentral.com/ domain. API users should make sure to only ever use the fully qualified domain name in their requests to our APIs, and never hardcode the IP this address resolves to. In order to provide a robust, highly available and scalable solution, Expedia Group may change the IP address being used without notice.

HTTP headers

Header

Type

Required

Input Format

Authorization

String

Required

Authorization: Basic [username:password encoded by Base64]

Content-Type

String

Required*

Content-Type: application/json

Accept

String

Required

Accept: application/json

Request-ID

String

Optional

Can be provided by you and can be referenced later on for troubleshooting purposes. When you provide the Request-ID, it can be anything, and no validations will be performed to ensure uniqueness of this ID. If it is not provided in request, the API will generate a Request-ID and return it in the response.

*required for create and modify requests only

Read a deposit policy

To obtain the deposit policy defined for a property, issue a GET request for the depositPolicy resource and specify the Expedia property ID as a path parameter.

  • Method: GET
  • URL: https://services.expediapartnercentral.com/properties/{propertyId}/depositPolicy
  • Consumes: HTTP Request (GET)
  • Produces: application/json

For our test property with Expedia property ID 12933870, this would be how:

GET https://services.expediapartnercentral.com/properties/12933870/depositPolicy

This policy defines both a default policy, applicable on any date, for any of the rate plans marked as using it. It also defines exceptions. Exceptions are overrides to the default, and will take precedence for the dates they cover.

Example syntax

If no deposit policy was ever defined for this property, or if a previously existing deposit policy was removed, a HTTP Status Code 404 / Not Found would be returned. In the policy exists, something like this would be returned:

1{
2 "entity": {
3 "defaultPolicy": {
4 "payments": [
5 {
6 "type": "PERCENT",
7 "value": 10,
8 "when": {
9 "type": "UPON_BOOKING"
10 }
11 },
12 {
13 "type": "PERCENT",
14 "value": 40,
15 "when": {
16 "type": "DAYS_PRIOR",
17 "value": 30
18 }
19 },
20 {
21 "type": "REMAINDER",
22 "when": {
23 "type": "UPON_ARRIVAL"
24 }
25 }
26 ]
27 },
28 "exceptionPolicies": [
29 {
30 "description": "High Season",
31 "payments": [
32 {
33 "type": "PERCENT",
34 "value": 50,
35 "when": {
36 "type": "UPON_BOOKING"
37 }
38 }
39 ],
40 "dateRanges": [
41 {
42 "startDate": "2020-07-30",
43 "endDate": "2020-08-30",
44 "daysOfWeek": ["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"]
45 },
46 {
47 "startDate": "2020-07-30",
48 "endDate": "2020-08-30",
49 "daysOfWeek": ["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"]
50 }
51 ]
52 },
53 {
54 "description": "Holiday Season",
55 "payments": [
56 {
57 "type": "PERCENT",
58 "value": 100,
59 "when": {
60 "type": "DAYS_PRIOR",
61 "value": 7
62 }
63 }
64 ],
65 "dateRanges": [
66 {
67 "startDate": "2020-12-17",
68 "endDate": "2020-01-06",
69 "daysOfWeek": ["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"]
70 },
71 {
72 "startDate": "2020-12-17",
73 "endDate": "2021-01-06",
74 "daysOfWeek": ["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"]
75 }
76 ]
77 }
78 ],
79 "_links": {
80 "self": {
81 "href": "https://services.expediapartnercentral.com/properties/12933870/depositPolicy"
82 },
83 "ratePlans": [
84 {
85 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706774/ratePlans/208503977"
86 },
87 {
88 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706774/ratePlans/208504009"
89 },
90 {
91 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706774/ratePlans/208537868"
92 },
93 {
94 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706639/ratePlans/208503427"
95 },
96 {
97 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706639/ratePlans/208511485"
98 },
99 {
100 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706639/ratePlans/208511588"
101 },
102 {
103 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706639/ratePlans/208537732"
104 },
105 {
106 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706639/ratePlans/208537755"
107 }
108 ]
109 }
110 }
111}

Success responses

Status Code

Description

Response Model

200

OK

SuccessfulGetResponse

Create or update a property’s deposit policy

To create or update a deposit policy, issue the request and specify the Expedia property ID as a path parameter.

  • Method: PUT
  • URL: https://services.expediapartnercentral.com/properties/{propertyId}/depositPolicy
  • Consumes: application/json
  • Produces: application/json
Example syntax
1{
2 "defaultPolicy": {
3 "payments": [
4 {
5 "type": "PERCENT",
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-06-25",
24 "endDate": "2020-07-31",
25 "daysOfWeek": ["SAT", "SUN"]
26 }
27 ],
28 "description": "Peak Summer Season Weekends",
29 "payments": [
30 {
31 "type": "PERCENT",
32 "value": 50,
33 "when": {
34 "type": "UPON_BOOKING"
35 }
36 }
37 ]
38 }
39 ]
40}

JSON attributes

Property Name

Type

Description

defaultPolicy

DefaultPolicy

Default policy. Applicable unless one or more exceptions are defined. Optional: it is possible to only define exception policies.

exceptionPolicies

Array[ExceptionPolicy]

Optional. Up to 4 exception policies can be defined. List of policies that override the default policy for the date range(s) specified in the exception. Order in the array of exception policies matters. The order of the elements in this array determines the order in which the policies should be applied in case of date overlap between exceptions.

_links

DepositPolicyLinks

Object describing links to other resources to which this deposit policy is linked to. Optional (i.e. ignored) when specified on PUT operation.

Default policy definition

Property Name

Type

Description

description

string

Default policy description. This field is optional.

payments

Array[PaymentPolicy]

List of payment policies. Up to 4 payment policies can be defined. Order of payments in the array matters.

Payments must be specified in chronological order: UPON_BOOKING followed by DAYS_PRIOR followed by UPON_ARRIVAL.

Also, when multiple payments with the type "percentage" are used, the sum of them cannot exceed 100.

Payment policy definition

Property Name

Type

Description

type

PaymentPolicyTypeEnum

Defines the type of payment policy.

value

number (double)

Indicates the amount of money that must be paid. If the type is REMAINDER, value cannot be specified. If type is either NIGHT or PERCENTAGE then the number must be whole (no fractional digits). Percentage cannot exceed 100. Expedia Traveler Preference properties cannot create UPON_BOOKING deposits greater than 50%.

when

PaymentTime

Indicates when the deposit is due.

Payment time definition

Order of payments in the array matters. Payments must be specified in chronological order: UPON_BOOKING followed by DAYS_PRIOR followed by UPON_ARRIVAL.

Property Name

Type

Description

type

PaymentTimeTypeEnum

Defines the type of payment time.

value

number (int32)

Only present if the type is DAYS_PRIOR. Indicates the number of days prior to arrival that the customer must pay the deposit.

Exception policy definition

Property Name

Type

Description

description

string

Exception policy description. This field is optional.

payments

Array[PaymentPolicy]

List of payment policies. Up to 4 payment policies can be defined.

dateRanges

Array[DateRange]

List of date range during which the exception policy applies. One exception can contain from 1 to 15 date ranges maximum.

Date range definition

Property Name

Type

Description

startDate

date

Starting date of the exception policy. Format is YYYY-MM-DD.

endDate

date

Ending date of the exception policy. Format is YYYY-MM-DD.

daysOfWeek

Array[DayOfWeekEnum]

List of days of the week the exception policy is applicable.

Object describing links to other resources to which this deposit policy is linked to.

Property Name

Type

Description

self

Link

Link to the current deposit policy.

ratePlans

Object describing a single link to a resource to which this deposit policy is linked to.

Collection of links to the rate plans (active and inactive) on which this deposit policy is applicable. The href property specifes the fully-qualified URL of the resource.

Success responses

Status Code

Description

Response Model

201

Created. The property didn't have a deposit policy, therefore it was created.

None

204

No Content. The property already had a deposit policy defined, and it was updated successfully.

None

Delete a property’s deposit policy

To delete a deposit policy, issue the request and specify the Expedia property ID as a path parameter. There is no JSON body.

  • Method: DELETE
  • URL: https://services.expediapartnercentral.com/properties/{propertyId}/depositPolicy
  • Produces: application/json

Success responses

Status Code

Description

Response Model

204

The property had a deposit policy and it was successfully deleted.

None

Examples

This section contains sample messages illustrating how to interact with Deposit API.

Reading a property’s deposit policy

To read the deposit policy of a property, a GET of /depositPolicy for the property will return it.

GET https://services.expediapartnercentral.com/properties/12933870/depositPolicy

Accept: application/json

1{
2 "entity": {
3 "defaultPolicy": {
4 "payments": [
5 {
6 "type": "PERCENT",
7 "value": 10,
8 "when": {
9 "type": "UPON_BOOKING"
10 }
11 },
12 {
13 "type": "PERCENT",
14 "value": 40,
15 "when": {
16 "type": "DAYS_PRIOR",
17 "value": 30
18 }
19 },
20 {
21 "type": "PERCENT",
22 "value": 25,
23 "when": {
24 "type": "DAYS_PRIOR",
25 "value": 15
26 }
27 },
28 {
29 "type": "REMAINDER",
30 "when": {
31 "type": "UPON_ARRIVAL"
32 }
33 }
34 ]
35 },
36 "exceptionPolicies": [
37 {
38 "description": "Peak Summer Season",
39 "dateRanges": [
40 {
41 "startDate": "2020-06-25",
42 "endDate": "2020-07-31",
43 "daysOfWeek": ["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"]
44 },
45 {
46 "startDate": "2020-08-13",
47 "endDate": "2020-08-31",
48 "daysOfWeek": ["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"]
49 }
50 ],
51 "payments": [
52 {
53 "type": "PERCENT",
54 "value": 50,
55 "when": {
56 "type": "UPON_BOOKING"
57 }
58 }
59 ]
60 },
61 {
62 "description": "Low Season",
63 "dateRanges": [
64 {
65 "startDate": "2020-09-01",
66 "endDate": "2020-11-30",
67 "daysOfWeek": ["SUN", "FRI", "SAT"]
68 }
69 ],
70 "payments": [
71 {
72 "type": "NIGHT",
73 "value": 1,
74 "when": {
75 "type": "UPON_BOOKING"
76 }
77 }
78 ]
79 }
80 ],
81 "_links": {
82 "self": {
83 "href": "https://services.expediapartnercentral.com/properties/12933870/depositPolicy"
84 },
85 "ratePlans": [
86 {
87 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706774/ratePlans/208503977"
88 },
89 {
90 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706774/ratePlans/208504009"
91 },
92 {
93 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706774/ratePlans/208537868"
94 },
95 {
96 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706639/ratePlans/208503427"
97 },
98 {
99 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706639/ratePlans/208511485"
100 },
101 {
102 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706639/ratePlans/208511588"
103 },
104 {
105 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706639/ratePlans/208537732"
106 },
107 {
108 "href": "https://services.expediapartnercentral.com/properties/12933870/roomTypes/201706639/ratePlans/208537755"
109 }
110 ]
111 }
112 }
113}

Creating the default deposit policy of a property

To set up the default deposit policy of a property, you can provide a policy without any exceptions. This example would setup a simple policy that is applicable all the time, where 50% of the payment is asked upfront upon booking and the remainder is collected upon arrival.

The response when successful will only return a "201 Created" without a response body.

PUT https://services.expediapartnercentral.com/properties/12933870/depositPolicy

1{
2 "defaultPolicy": {
3 "payments": [
4 {
5 "type": "PERCENT",
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}

Specifying exceptions to a property’s default deposit policy

In addition to the default policy, you can also specify exceptions that are applicable for certain date ranges. In this example, the default deposit policy would be overridden for weekends between June 25th and July 31st where 100% of the payment is asked upfront upon booking, instead of the default policy where only half required upon booking and the remainder is collected upon arrival.

PUT https://services.expediapartnercentral.com/properties/12933870/depositPolicy

1{
2 "defaultPolicy": {
3 "payments": [
4 {
5 "type": "PERCENT",
6 "value": 40,
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-06-25",
24 "endDate": "2020-07-31",
25 "daysOfWeek": ["SAT", "SUN"]
26 }
27 ],
28 "description": "Peak Summer Season Weekends",
29 "payments": [
30 {
31 "type": "PERCENT",
32 "value": 30,
33 "when": {
34 "type": "UPON_BOOKING"
35 }
36 }
37 ]
38 }
39 ]
40}