Create/Update Policies

This endpoint allows users to create or modify policies for properties. The policies are essential in defining cancellation penalties, no-show penalties, and guarantee payment requirements for reservations.

Create/Update Policies API Rules

The Policies API allows you to create, modify, and retrieve policies for your properties. Currently, it supports the creation of cancellation policies, which define the penalty conditions applied when a guest cancels a reservation.
Cancellation policies are specific to each property. You must create these policies at the property level, but they are assigned at the room rate level.
When creating a cancellation policy, you can define the following penalty conditions:
- Cancellation penalty fee (using a cancellation penalty code)
- Guarantee payment fee
- No-show penalty fee
Upon the successful creation of a cancellation policy, the API will return a policy ID, which can be used to uniquely identify the cancellation policy and its associated penalty conditions.
Policy count limit: The Policies API allows you to create up to a maximum of 7 cancellation policies per property.

Endpoint

POST

https://connect-sandbox.su-api.com/SUAPI/jservice/bdc/policies/set

Header

-app-id: YOUR_APP_ID
Authorization: YOUR_API_KEY
Content-Type:application/json

Header

Type

Required

Description

app-id

string

Yes

Your application ID. Required for authentication.

Authorization

string

Yes

Your API key. for authorization. Required for authentication.

Content-Type

string

Yes

Must be set to application/json.

Attributes

hotel_id string (Required)

Specifies the hotel ID for the property.

channel_hotel_id string (Required)

Specifies the channel-specific hotel ID for the property.

policy_id string (Required)

This represents the unique identifier of the policy being updated or created.

NOTE

The policy_id will be included in the request code only when updating an existing policy. For the creation of a new policy, the policy_id will be generated after the policy is successfully created and will not be available in the request code.

policy_type string (Required)

Specifies the policy type.

Currently, the API supports only Cancellation.

cancel_penalty object (Required)

Contains the details of the cancellation penalty assigned to the policy.

policy_code integer (Required)

Specifies the Booking.com cancellation code that suits your business needs.

noshow_policy object (Optional)

Contains the no show penalty details.

penalty string (Optional)

Specifies the penalty charged in case the guest does not turn up for the reservation.

Possible values are: - default: Use if you want the no show penalty to follow the cancellation fee. - total_price: Use if you want the no show penalty to equal the total reservation price.

By default, the API creates a policy with a no show penalty that equals the cancellation penalty.

guarantee_payment object (Required)

Contains guarantee payment details.

Certain penalty codes accept only specific combinations of required and effective_from values. For example, a non-refundable penalty code must have the required attribute always set to true and the fully-flexible penalty code must have the required attribute always set to false.

Except for the penalty codes specified in the Penalty code and guarantee payment matrix (below), you have the freedom to specify any guarantee payment value for all other penalty codes.

Penalty code and guarantee payment matrix

The following table contains cancellation policy codes that need specific guarantee_payment required and effective_from values.

Cancel Penalty Code

Guarantee payment required

Guarantee payment EffectiveFrom

Notes

true

after_reservation_is_made

Non-refundable policy.

152

false

Not applicable

Fully flexible policy.

166

true

after_reservation_is_made

Partially refundable policy.

168

true

after_reservation_is_made

Partially refundable policy.

required boolean (Required)

Indicates whether a guarantee payment is mandatory.

Possible values are: - true: Guarantee payment required - false: Guarantee payment is not required

For cancel_penalty policy_code= 1,152,166 and 168, see the Penalty code and guarantee payment matrix (above)

effective_from string (Optional)

Specifies when the guarantee payment is charged.

mandatory only when required = "true"

Possible values are: - after_reservation_is_made: Use if you want the guests to make a payment immediately after reservation. - after_cancellation_fee_begins: Use if you want the guests to make a payment after the free cancellation window has closed.

If required = "false", then any value provided here is ignored. For cancel_penalty policy_code = 1, 166 and 168, see the Penalty code and guarantee payment matrix (above)

Sample Request

{
   "hotel_id": "AWSTEST",
   "channel_hotel_id": "12837615",
   "policy_id": "401318362",
   "policy_type": "Cancellation",
   "cancel_penalty": {
       "policy_code": "55"
   },
   "noshow_policy": {
       "penalty": "total_price"
   },
   "guarantee_payment": {
       "required": "false",
       "effective_from": "after_reservation_is_made"
   }
}

Response

Sample Success Response

{
   "Status": "Success",
   "Message": "Policy details set successfully",
   "Ruid": "",
   "Data": [
       {
           "id": "401318362",
           "group_name": "general",
           "policy_type": "Cancellation",
           "cancel_penalty": {
               "policy_code": "16",
               "penalty_description": "The guest can cancel free of charge until 5 days before arrival. The guest will be charged the total price of the reservation if they cancel in the 5 days before arrival. If the guest doesn't show up, they will be charged the total price of the reservation."
           },
           "noshow_policy": {
               "penalty": "total_price"
           },
           "guarantee_payment": {
               "required": "true",
               "effective_from": "after_reservation_is_made",
               "description": "The guest will be charged a prepayment of the total price of the reservation at any time."
           }
       }
   ]
}

Success Response Body Elements

Status string

Indicates the result of the API call.

Will be "Success" for successful operations.

Data array

Contains the main data returned by the API, which in this case is a list of policies related to cancellations, guarantees, and penalties.

Each object represents a policy with various associated details.

id integer

Specifies the uniquely identifiable policy ID.

Use this value to make subsequent edits to the policy. However, the policy ID remains unchanged across the policy's lifespan.

group_name string

Specifies the internal policy name. group_name and Policy ID are unrelated.

The group name does not hold any logic and is randomly assigned, except for 'general' which indicates it is the default policy. However, you can use a policy's group name to identify it in the extranet. In future, group_name may get deprecated.

policy_type string

Specifies the policy type.

Currently, the API supports only Cancellation.

cancel_penalty object

Contains the details of the cancellation penalty assigned to the policy.

policy_code integer

Specifies the Booking.com cancellation code that was included in the request.

penalty_description string

Contains the cancellation penalty description.

noshow_policy object

Contains the no show penalty details.

penalty string

Specifies the penalty charged in case the guest does not turn up for the reservation.

Possible values are: - default: Use if you want the no show penalty to follow the cancellation fee. - total_price: Use if you want the no show penalty to equal the total reservation price.

guarantee_payment object

Contains the guarantee payment details.

required boolean

Specifies whether a guarantee payment is mandatory.

Possible values are: - true: Guarantee payment required - false: Guarantee payment is not required

effective_from string

Specifies when the guarantee payment is charged.

Possible values are:

- after_reservation_is_made: Enforces guests to make a payment immediately after reservation. - after_cancellation_fee_begins: Enforces guests to make a payment after the free cancellation window has closed.

description string

Specifies the guarantee payment in natural language.

Currently, the API supports description text in English.

Message string

A message receives within the response body. This will generally be an empty string if no additional information is needed.

Ruid string

Specifies the unique request ID.

You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.

Errors

Sample Error Response 1

{
   "Errors": [
       {
           "Code": "400",
           "ShortText": "HotelCode: Invalid HotelCode ('AWSTEST')"
       }
   ],
   "Status": "Fail"
}

Sample Error Response 2

{
   "Errors": [
       {
           "Code": "573",
           "ShortText": "channel-mapping not found for this property!"
       }
   ],
   "Status": "Fail"
}

Sample Error Response 3

When cancel_penalty - policy_code is invalid or not found

{
   "Status": "Fail",
   "Errors": [
       {
           "Code": "812",
           "ShortText": "cancel_penalty - policy_code: value invalid or not found!"
       }
   ],
   "Message": "",
   "Ruid": ""
}

Sample Error Response 4

When error was thrown from booking.com then error structure will be like this

{
   "Status": "Fail",
   "Errors": [],
   "Message": "(403628216) DUPLICATE_POLICY: Cannot have 2 policies with the same cancellation and prepayment codes",
   "Ruid": "",
   "Data": [
       {
           "id": "403628216",
           "group_name": "fully flexible",
           "policy_type": "Cancellation",
           "cancel_penalty": {
               "policy_code": "55",
               "penalty_description": ""
           },
           "noshow_policy": {
               "penalty": "total_price"
           },
           "guarantee_payment": {
               "required": "true",
               "effective_from": "after_reservation_is_made",
               "description": ""
           }
       }
   ]
}

Error Response Body Elements

Status string

Indicates the result of the API call, which will be always "Fail" in case of an error response.

Error array

Array that contains details about any errors that occurred during the API call. Each object in the Errors array contains the following properties:

Code string

Specific error code that helps identify the type of error.

For example: "400" indicates a bad request.

ShortText string

A short description of the error.

Message string

A message providing more information about the error.

Ruid string

Specifies the unique request ID.

You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.

In the case where a RUID (Request Unique Identifier) is provided by Booking.com, it will be displayed in the response. If no RUID is received, the field will be left blank.

PreviousPolicies API NextRetrieve Policies

Last updated 8 months ago

Was this helpful?