Rate Parentage Management - API

Method to retrieve and manage parentage modifiers for derived rates

Some rates may be configured such that their price is not set directly, but rather be derived from another rate (aka the parent rate) based on some modifier values. Such rates are also called child rates.

You can tell if a rate is child by the parent field of the Rates Listing or Rate Info API response. Α parent value greater than 0, indicates that the rate is a child rate and the rate ID of it's parent is returned here.

Limited Beta

The rate parentage API methods are currently in limited beta. Please contact us first if you want to use them.

JSON output

The rate parentage API methods only support JSON response format. To get a response in JSON make sure you are also sending the Accept: application/json header.


Table of Contents
  1. GET - List all parentage periods for a rate
  2. POST - Create parentage override period
  3. GET - Get parentage period info
  4. PUT - Update parentage period
  5. DELETE - Delete parentage override period


GET - List parentage periods for a rate

To list all parentage periods, use GET http verb.


URL Endpoint

/rate/{property_code}/{unit_type}/{rate_id}/parentage

Method Parameters

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
modifiers boolean NO false &modifiers=true The default value is false

JSON Response Schema

{
    "method": "https://rest.reserve-online.com/rate/{property_code}/{unit_type}/{rate_id}/parentage",
    "http_method": "GET",
    "http_code": 200,
    "error_code": "OK",
    "error_msg": "",
    "params": [
        {
            "type": "URL",
            "name": "modifiers",
            "value": false
        }
    ],
    "data": {
        "periods": [
            {
                "period_id": INTEGER, // Period id
                "from": ISO 8601, // Start of date range inclusive. This field will not be included for the default period (period_id=0)
                "to": ISO 8601, // End of date range. This field will not be included for the default period (period_id=0)
                "modifiers": [  // Modifiers will be included conditionally when the request parameter `modifiers=true`
                    {
                        "adults": INTEGER, // Number of adults
                        "children": INTEGER, // Number of children
                        "percent": DECIMAL, // Percentile change on the parent rate. Positive numbers increase the price and negative decrease it.
                        "amount": MONEY // The absolute change on the parent rate. Positive numbers increase the price and negative decrease it.
                    }
                ]
            }
        ]
    }
}

JSON Response Example

{
    "method": "http://rest.reserve-online.com/rate/DEMO/FML/12345/parentage",
    "http_method": "GET",
    "http_code": 200,
    "error_code": "OK",
    "error_msg": "",
    "params": [
        {
        "type": "URL",
        "name": "modifiers",
        "value": false
        }
    ],
    "data": {
        "periods": [
            {
                "period_id": 0,
                "modifiers": [
                    {
                        "adults": 1,
                        "children": 0,
                        "percent": 20,
                        "amount": 0
                    },
                    {
                        "adults": 2,
                        "children": 0,
                        "percent": 20,
                        "amount": 0
                    }
                ]
            },
            {
                "period_id": 1,
                "from": "2023-12-18",
                "to": "2023-12-18",
                "modifiers": [
                    {
                        "adults": 1,
                        "children": 0,
                        "percent": 20,
                        "amount": 5
                    },
                    {
                        "adults": 2,
                        "children": 0,
                        "percent": 20,
                        "amount": 10
                    }
                ]
            }
        ]
    }
}


POST - Create a parentage override period

To create a new parentage override period, use POST http verb. The request payload must contain the from/to dates and modifiers


Request body

Request body must be in valid JSON format.

Send header Content-Type: application/json

Update is made only if the entire request body is successfully parsed and validated.

Periods

The rate must already be defined as derived/child through the WebHotelier extranet. You can not create the default period, i.e. make a rate child if it isn't already.

Overlapping periods are not allowed. If any date of the period overlaps an existing one, an error is returned and the update is not applied.

Pax combinations

The modifiers array must contain all possible pax combinations supported for the room type the rate belongs to. If not all pax combinatios are provided or any invalid ones are included, an error is returned and the update is not applied.

To get the list of pax combinations, use the Rates Feed API for this specific rate (/manage/rates/{rate_id}).

Modifier values

A modifiers.percent positive value of 20 means that a 20% increase will be applied to the parent rate price.
For example:

  • If the parent rate price is 80 EUR, the child rate price will be ((100+20)/100)*80=96 EUR.
  • If you set a negative value e.g "percent": -15, the final price would be ((100-15)/100)*80=68 EUR.

The amount modifier is applied after the percent calculation.
Using the above example:

  • If the request included a modifiers.amount value of 5, the final price would be 96+5=101 EUR, or 68+5=73 EUR for the negative percentage case.
  • If the amount value is negative, it will be subtracted from the parent rate price.
    For a value of -5, the final price would be 96-5=91 EUR, or 68-5=63 EUR for the negative percentage case.

URL Endpoint

/rate/{property_code}/{unit_type}/{rate_id}/parentage

The request payload should have the following structure:

{
    "from": ISO 8601, // Start of date range inclusive
    "to": ISO 8601, // End of date range
    "modifiers": [
        {
            "adults": INTEGER, // Number of adults
            "children": INTEGER, // Number of children
            "percent": DECIMAL, // Percentile change on the parent rate. Use positive numbers to increase and negative to decrease
            "amount": MONEY // The absolute change on the parent rate. Use positive numbers to increase and negative to decrease
        }
    ]
}

POST request example

{
    "from": "2023-12-18",
    "to": "2023-12-18",
    "modifiers": [
        {
            "adults": 1,
            "children": 0,
            "percent": 20,
            "amount": 0
        },
        {
            "adults": 2,
            "children": 0,
            "percent": 15,
            "amount": 10
        }
    ]
}

JSON Response Schema

{
    "method": "https://rest.reserve-online.com/rate/{property_code}/{unit_type}/{rate_id}/parentage",
    "http_method": "POST",
    "http_code": 200,
    "error_code": "OK",
    "error_msg": "",
    "params": [],
    "data": {
        "period_id": INTEGER, // Period id
        "from": ISO 8601, // Start of date range inclusive
        "to": ISO 8601, // End of date range
        "modifiers": [
            {
                "adults": INTEGER, // Number of adults
                "children": INTEGER, // Number of children
                "percent": DECIMAL, // Percentile change on the parent rate. Positive numbers increase the price and negative decrease it.
                "amount": MONEY // The absolute change on the parent rate. Positive numbers increase the price and negative decrease it.
            }
        ]
    }
}

JSON Response Example

{
    "method": "http://rest.reserve-online.com/rate/DEMO/FML/12345/parentage",
    "http_method": "POST",
    "http_code": 200,
    "error_code": "OK",
    "error_msg": "",
    "params": [],
    "data": {
        "period_id": 0,
        "from": "2023-12-18",
        "to": "2023-12-18",
        "modifiers": [
            {
                "adults": 1,
                "children": 0,
                "percent": 20,
                "amount": 0
            },
            {
                "adults": 2,
                "children": 0,
                "percent": 15,
                "amount": 10
            }
        ]
    }
}


GET - Get parentage period

To get a specific parentage period and its details, use GET http verb with the appropriate period_id value:


URL Endpoints

/rate/{property_code}/{unit_type}/{rate_id}/parentage/{period_id}

JSON Response Schema

{
    "method": "https://rest.reserve-online.com/rate/{property_code}/{unit_type}/{rate_id}/parentage/{period_id}",
    "http_method": "GET",
    "http_code": 200,
    "error_code": "OK",
    "error_msg": "",
    "params": [],
    "data": {
        "period_id": INTEGER, // Period id
        "from": ISO 8601, // Start of date range inclusive. This field will not be included for the default period (period_id=0)
        "to": ISO 8601, // End of date range. This field will not be included for the default period (period_id=0)
        "modifiers": [
            {
                "adults": INTEGER, // Number of adults
                "children": INTEGER, // Number of children
                "percent": DECIMAL, // Percentile change on the parent rate. Positive numbers increase the price and negative decrease it.
                "amount": MONEY // The absolute change on the parent rate. Positive numbers increase the price and negative decrease it.
            }
        ]
    }
}

JSON Response Example

{
    "method": "http://rest.reserve-online.com/rate/DEMO/FML/12345/parentage/0",
    "http_method": "GET",
    "http_code": 200,
    "error_code": "OK",
    "error_msg": "",
    "params": [],
    "data": {
        "period_id": 0,
        "modifiers": [
            {
                "adults": 1,
                "children": 0,
                "percent": 20,
                "amount": 0
            },
            {
                "adults": 2,
                "children": 0,
                "percent": 15,
                "amount": 10
            }
        ]
    }
}


PUT - Update parentage period

To update a Rate Parentage Period, use PUT http verb with the appropriate period_id value. The request payload must contain the from/to dates and modifiers

Notice

All requirements and guidelines of the POST method apply to the PUT method as well.


URL Endpoints

/rate/{property_code}/{unit_type}/{rate_id}/parentage/{period_id}

The request payload should have the following structure:

{
    "from": ISO 8601, // Start of date range inclusive. This field should not be included for the default period with period_id=0
    "to": ISO 8601, // End of date range. This field should not be included for the default period with period_id=0
    "modifiers": [
        {
            "adults": INTEGER, // Number of adults
            "children": INTEGER, // Number of children
            "percent": DECIMAL, // Percentile change on the parent rate. Use positive numbers to increase and negative to decrease
            "amount": MONEY // The absolute change on the parent rate. Use positive numbers to increase and negative to decrease
        }
    ]
}

PUT request example

{
    "period_id": 1,
    "from": "2024-01-10",
    "to": "2024-01-31",
    "modifiers": [
        {
            "adults": 1,
            "children": 0,
            "percent": 10,
            "amount": 0
        },
        {
            "adults": 2,
            "children": 0,
            "percent": 10,
            "amount": 5
        }
    ]
}

JSON Response Schema

{
    "method": "https://rest.reserve-online.com/rate/{property_code}/{unit_type}/{rate_id}/parentage/{period_id}",
    "http_method": "PUT",
    "http_code": 200,
    "error_code": "OK",
    "error_msg": "",
    "params": [],
    "data": {
        "period_id": INTEGER, // Period id
        "from": ISO 8601, // Start of date range inclusive. This field must not be sent for the default period (period_id=0)
        "to": ISO 8601, // End of date range. This field must not be sent for the default period (period_id=0)
        "modifiers": [
            {
                "adults": INTEGER, // Number of adults
                "children": INTEGER, // Number of children
                "percent": DECIMAL, // Percentile change on the parent rate. Use positive numbers to increase and negative to decrease
                "amount": MONEY // The absolute change on the parent rate. Use positive numbers to increase and negative to decrease
            }
        ]
    }
}

JSON Response Example

{
    "method": "http://rest.reserve-online.com/rate/DEMO/FML/12345/parentage/0",
    "http_method": "PUT",
    "http_code": 200,
    "error_code": "OK",
    "error_msg": "",
    "params": [],
    "data": {
        "period_id": 0,
        "modifiers": [
            {
                "adults": 1,
                "children": 0,
                "percent": 20,
                "amount": 0
            },
            {
                "adults": 2,
                "children": 0,
                "percent": 15,
                "amount": 10
            }
        ]
    }
}


DELETE - Delete parentage override period

To delete a Rate Parentage Period, use DELETE http verb with the appropriate period_id value.


Warning

You are not allowed to delete the default period (period_id=0).


URL Endpoints

/rate/{property_code}/{unit_type}/{rate_id}/parentage/{period_id}

JSON response example

{
    "method": "http://rest.reserve-online.com/rate/DEMO/FML/12345/parentage/1",
    "http_method": "DELETE",
    "http_code": 200,
    "error_code": "OK",
    "error_msg": ""
}