Cancellation Policy

The Cancellation Policy Metadata request, initiated by Hotel Trader, contains detailed cancellation policy information such as penalty windows, penalty amount, etc.

A single cancellation policy can be set up to have multiple penalty windows which is also called a staggered cancellation policy.

Initiator - Hotel Trader

Endpoint

New Cancellation Policies

Creates single or multiple cancellation policies for the first time in the client system.

[POST] https://<client-base-url>/cancellation-policies

Update existing cancellation policies

Updates a single existing cancellation policy in the client system.

[PUT] https://<client-base-url>/cancellation-policy/<code>

Request

HTTP Headers

All HTTP headers are mandatory and apply consistently across both endpoints of the API.

Clients must provide their username and password to Hotel Trader. For more information on username and password encoding, please refer to the Authentication page in our Knowledge Base.

Header Name	Type
Content-Type	application/json
Accept-Encoding	gzip
Authorization	Basic <token>

Request Description

All the fields in the request are described below.

Field/Object	Datatype	Required	Description
messageId	String	Yes	A string that uniquely identifies this particular message. This should be returned in the response.
updateType	String	Yes	The type of cancellation policy update. Possible values - NEW, UPDATE. ENABLED and DISABLED are not allowed for this API. More information on this object can be found here.
propertyCode	String	Yes	A unique hotel code provided by Hotel Trader identifies the hotel for which cancellation policy metadata is sent in this request.
cancellationPolicies	Array	Yes	An array of cancellation policy objects.

Field/Object	Datatype	Required	Description
name	String	Yes	The name of the cancellation policy
code	String	Yes	A code provided by Hotel Trader that identifies this cancellation policy. This code is unique for each cancellation policy for a property.
description	String	Yes	A short description of the cancellation policy.
penaltyWindows	Array	Yes	An array of penalty window objects each specifying deadlines and penalties.

Penalty Window

The penaltyWindow node must include either absoluteDeadline or relativeDeadline, but not both simultaneously.

Field/Object	Datatype	Required	Description
absoluteDeadline	String	No	The absolute timestamp on the arrival day in HH: MM in 24-hour format.
relativeDeadline	Object	No	If the penalty window is relative to the check-in date or booking date, use the relative deadline object.
penalty	Object	Yes	Penalty details associated with this policy window.

Relative Deadline

Field/Object	Datatype	Required	Description
relativeTo	String	Yes	Indicates the reference point for the relative deadline. Possible values: BOOKING_CREATION, CHECKIN_TIME, CHECKIN_DAY_MIDNIGHT.
type	String	Yes	Specifies whether the relative deadline is before or after the reference point. Possible values: BEFORE, AFTER.
offsetUnit	String	Yes	The unit of the offset for the relative deadline. Possible values: DAY, HOUR, MINUTE.
offsetValue	Integer	Yes	The numeric value for the offset indicates how many units before or after the reference point the deadline is set.

Penalty

For the penalty node, exactly one of flat, percent, or nights must be provided. Multiple values are not allowed.

Field/Object	Datatype	Required	Description
flat	Float	No	Specifies the flat penalty amount.
percent	Float	No	Specifies the penalty as a percentage.
nights	Integer	No	Indicates the number of nights to which the penalty applies.
taxInclusive	Boolean	Yes	Indicates whether the penalty includes taxes.

Example

Request for adding a new cancellation policy

{
    "messageId": "s6aa3d81-6c1d-4e12-b374-c76735b49fc9",
    "updateType": "UPDATE",
    "propertyCode": "NYCMIL",
    "cancellationPolicies": [
        {
            "code": "CP001",
            "name": "Standard Cancellation Policy",
            "description": "Free cancellation up to 24 hours before check-in.",
            "penaltyWindows": [
                {
                    "relativeDeadline": {
                        "relativeTo": "CHECKIN_TIME",
                        "type": "Before",
                        "offsetUnit": "HOUR",
                        "offsetValue": 24
                    },
                    "penalty": {
                        "percent": null,
                        "nights": 1,
                        "taxInclusive": true
                    }
                }
            ]
        }
    ]
}

Request for updating an existing cancellation policy

{
    "messageId": "s6aa3d81-6c1d-4e12-b374-c76735b49fc9",
    "updateType": "UPDATE",
    "propertyCode": "NYCMIL",
    "cancellationPolicy": {
            "code": "CP001",
            "name": "Standard Cancellation Policy",
            "description": "Free cancellation up to 24 hours before check-in.",
            "penaltyWindows": [
                {
                    "relativeDeadline": {
                        "relativeTo": "CHECKIN_TIME",
                        "type": "Before",
                        "offsetUnit": "HOUR",
                        "offsetValue": 24
                    },
                    "penalty": {
                        "percent": null,
                        "nights": 1,
                        "taxInclusive": true
                    }
                }
            ]
        }
}

Response

This API follows the Standard Response model of the Metadata Push API.

Cancellation Policy API