> For the complete documentation index, see [llms.txt](https://suissu.gitbook.io/su-api-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://suissu.gitbook.io/su-api-documentation/su-channel-manager/channel-content-api/booking.com-content-api/policies-api/create-update-policies.md).

# 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.

## <mark style="color:yellow;">**Create/Update Policies API Rules**</mark>

* 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.

***

### <mark style="color:yellow;">Endpoint</mark>

<mark style="color:green;background-color:green;">**`POST`**</mark>&#x20;

<div align="left"><figure><img src="https://958347541-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM9bn2UcBkeqtqixkl5eF%2Fuploads%2FpsybX0n39kUB8Z8WOk4X%2FSandbox%20image.png?alt=media&amp;token=4ae73d0f-0d1a-4d73-a4e2-673dbc081d6a" alt="" width="56"><figcaption></figcaption></figure></div>

{% code overflow="wrap" %}

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

{% endcode %}

***

#### <mark style="color:yellow;">Attributes</mark>

`hotel_id` <mark style="color:orange;">**string (Required)**</mark>

Specifies the hotel ID for the property.

***

`channel_hotel_id` <mark style="color:orange;">**string (Required)**</mark>

Specifies the channel-specific hotel ID for the property.

***

`policy_id` <mark style="color:orange;">**string (Required)**</mark>

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

{% hint style="info" %}
**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.&#x20;
{% endhint %}

***

`policy_type` <mark style="color:orange;">**string (Required)**</mark>

Specifies the policy type.

{% hint style="info" %}
Currently, the API supports only `Cancellation`.
{% endhint %}

***

`cancel_penalty` <mark style="color:orange;">**object (Required)**</mark>

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

`policy_code` <mark style="color:orange;">**integer (Required)**</mark>

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

***

`noshow_policy` <mark style="color:orange;">**object (Optional)**</mark>

Contains the no show penalty details.

`penalty` <mark style="color:orange;">**string (Optional)**</mark>

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

{% hint style="info" %}
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.<br>

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

***

`guarantee_payment` <mark style="color:orange;">**object (Required)**</mark>

Contains guarantee payment details.

{% hint style="info" %}
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`.&#x20;

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.
{% endhint %}

#### Penalty code and guarantee payment matrix <a href="#penalty-code-and-guarantee-payment-matrix" id="penalty-code-and-guarantee-payment-matrix"></a>

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

<table><thead><tr><th width="203">Cancel Penalty Code</th><th>Guarantee payment required</th><th>Guarantee payment EffectiveFrom</th><th>Notes</th></tr></thead><tbody><tr><td>1</td><td>true</td><td>after_reservation_is_made</td><td>Non-refundable policy.</td></tr><tr><td>152</td><td>false</td><td>Not applicable</td><td>Fully flexible policy.</td></tr><tr><td>166</td><td>true</td><td>after_reservation_is_made</td><td>Partially refundable policy.</td></tr><tr><td>168</td><td>true</td><td>after_reservation_is_made</td><td>Partially refundable policy.</td></tr></tbody></table>

`required` <mark style="color:orange;">**boolean (Required)**</mark>

Indicates whether a guarantee payment is mandatory.

{% hint style="info" %}
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)
{% endhint %}

`effective_from` <mark style="color:orange;">**string (Optional)**</mark>

Specifies when the guarantee payment is charged.

{% hint style="info" %}
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.<br>

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)
{% endhint %}

***

## <mark style="color:yellow;">**Sample Request**</mark>

```json
{
   "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"
   }
}
```

***

## <mark style="color:yellow;">Response</mark>

#### <mark style="color:green;">**Sample Success Response**</mark>

```json
{
   "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."
           }
       }
   ]
}
```

#### <mark style="color:yellow;">Success Response Body Elements</mark>

`Status` <mark style="color:orange;">**string**</mark>

Indicates the result of the API call.&#x20;

{% hint style="info" %}
Will be `"Success"` for successful operations.
{% endhint %}

***

`Data` <mark style="color:orange;">**array**</mark>

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

Each object represents a policy with various associated details.

`id` <mark style="color:orange;">**integer**</mark>&#x20;

Specifies the uniquely identifiable policy ID.

{% hint style="info" %}
Use this value to make subsequent edits to the policy. However, the policy ID remains unchanged across the policy's lifespan.
{% endhint %}

`group_name` <mark style="color:orange;">**string**</mark>

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` <mark style="color:orange;">**string**</mark>

Specifies the policy type.

{% hint style="info" %}
Currently, the API supports only `Cancellation`.
{% endhint %}

`cancel_penalty` <mark style="color:orange;">**object**</mark>

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

`policy_code` <mark style="color:orange;">**integer**</mark>

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

`penalty_description` <mark style="color:orange;">**string**</mark>

Contains the cancellation penalty description.

`noshow_policy` <mark style="color:orange;">**object**</mark>

Contains the no show penalty details.

`penalty` <mark style="color:orange;">**string**</mark>

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

{% hint style="info" %}
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.
{% endhint %}

`guarantee_payment` <mark style="color:orange;">**object**</mark>

Contains the guarantee payment details.

`required` <mark style="color:orange;">**boolean**</mark>

Specifies whether a guarantee payment is mandatory.

{% hint style="info" %}
Possible values are:\
\- `true`: Guarantee payment required\
\- `false`: Guarantee payment is not required
{% endhint %}

`effective_from` <mark style="color:orange;">**string**</mark>

Specifies when the guarantee payment is charged.

{% hint style="info" %}
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.
{% endhint %}

`description` <mark style="color:orange;">**string**</mark>

Specifies the guarantee payment in natural language.

{% hint style="info" %}
Currently, the API supports description text in English.
{% endhint %}

***

`Message` <mark style="color:orange;">**string**</mark>

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

***

`Ruid` <mark style="color:orange;">**string**</mark>&#x20;

Specifies the unique request ID.&#x20;

{% hint style="info" %}
You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.
{% endhint %}

#### <mark style="color:red;">Errors</mark>

<mark style="color:red;">**Sample Error Response 1**</mark>

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

<mark style="color:red;">**Sample Error Response 2**</mark>

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

<mark style="color:red;">**Sample Error Response 3**</mark>

When `cancel_penalty - policy_code` is invalid or not found

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

<mark style="color:red;">**Sample Error Response 4**</mark>

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

```json
{
   "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": ""
           }
       }
   ]
}
```

***

<mark style="color:yellow;">**Error Response Body Elements**</mark>

`Status` <mark style="color:orange;">**string**</mark>

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

***

`Error` <mark style="color:orange;">**array**</mark>

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

`Code` <mark style="color:orange;">**string**</mark>

Specific error code that helps identify the type of error.

{% hint style="info" %}
For example: `"400"` indicates a bad request.
{% endhint %}

`ShortText` <mark style="color:orange;">**string**</mark>

A short description of the error.

***

`Message` <mark style="color:orange;">**string**</mark>

A message providing more information about the error.

***

`Ruid` <mark style="color:orange;">**string**</mark>&#x20;

Specifies the unique request ID.&#x20;

{% hint style="info" %}
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.
{% endhint %}