{{ wiki:www.travanto.de.png}} \\ \\ \\ \\ ====== Price services ====== The price services are one of the most crucial and most comprehensive services. Pricing information is quite sensitive and needs to be handled with care especially if your properties are bookable online. If you have any doubts, concerns or questions, please contact us before developing in the wrong direction. ;-) Some pricing information relate to a specific season others are only valid per property. All booking rules (determining whether or not a booking can be made) can differ from season to season. This way, you can, for example, set different arrival and departure days or determine the gap between booking and arrival for different seasons throughout the year. Please see Booking rules at the bottom of the page for further details. The general URL of this service is https://connect.travanto.de/service/prices/. Use GET, POST, PUT and DELETE methods to show, create, change or delete one or more price periods/seasons. The [[api:services:schemata:prices|basic pricing schemata]] already includes different settings for booking rules. Don't be confused, we have explained them in detail right here. \\ \\ \\ ===== A. Price settings (per season) ===== ==== Rental prices ==== Rental prices need to be presented per night. Weekly or biweekly prices are not permitted. They are calculated internally based on the daily price information. This also includes long stay discounts as well as extra person surcharges. More detailed information can be found below. ==== Long stay discounts ==== Long stay discounts are also related to a specific season. You can choose up to three different discounts in combination with varying minimum stays. ==== Service methods ==== ^ Method ^ URL ^ Description ^ | POST |/service/prices/ | Create one or more periods/seasons for one or more properties | | GET |/service/prices/ | Show all current seasons for all your properties. | | GET |/service/prices/$price_id | Get all details for one specific period. | | PUT |/service/prices/ | Change one or more seasons for various properties | | DELETE |/service/prices/$price_id| Delete one specific season | | DELETE |/service/prices/?object_id=$object_id| Delete ALL season for one specific property. CAREFUL!!! | The [[api:services:schemata:prices|basic request and response schemes]] for the prices services provide you with a sound idea of how to use it. Price service request scheme\\ Price service response scheme \\ === Example POST request === [json indentation=keep] { "prices": [ { "object_id": 1010397, "name": "Temporary season", "from": "2016-08-01", "to": "2016-09-30", "price": 50, "min_stay": 7, "discounts": [ { "min_stay": 10, "price": 40 }, { "min_stay": 14, "price": 35 } ], "mandatory_gap": 0, "conditional_gap": 7, "min_nights_to_arrival": 2, "arrival_weekdays": [ "Fri", "Sat", "Sun" ], "departure_weekdays": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ], "deactivate_weekdays_for_gaps": false, "deactivate_min_stay_for_gaps": true } ] } [/json] Example response: [json indentation=keep] { "OK": 1, "Request": { "Method": "POST", "Path": "/service/prices/" }, "PricesServiceResult": [ { "price_id": 1676536, "object_id": 1010397, "name": "Temporary season", "from": "2016-08-01", "to": "2016-09-30", "price": 50, "min_stay": 7, "mandatory_gap": 0, "conditional_gap": 7, "min_nights_to_arrival": 2, "deactivate_min_stay_for_gaps": true, "deactivate_weekdays_for_gaps": false, "discounts": [ { "min_stay": 10, "price": 40 }, { "min_stay": 14, "price": 35 } ], "arrival_weekdays": [ "Fri", "Sat", "Sun" ] } ] } [/json] Tips: * Creating a season does of course not require a "price_id". It is being generated internally and returned to you within the response. Use it for all further actions concerning this season. * ==== Error Codes ==== \\ApiMethodException 10056 - if the URL contains an entity id\\ \\ApiJsonException 10241 - if the HTTP body contains invalid JSON\\ \\ApiJsonException 10249 - if the JSON data is violating the JSON Schema of this Service\\ \\ApiInputException 10227 - if the from date is after the to date\\ \\ApiInputException 10226 - if the to date is in the past\\ \\ApiInputException 10274 - if mandatory_gap is greater than the user-defined maximum value\\ \\ApiInputException 10274 - if min_nights_to_arrival is greater than the user-defined maximum value\\ \\ApiInputException 10260 - if there is a discount that has not a greater min_stay value than the price period\\ \\ApiInputException 10258 - if there is a discount that has not a lower price value than the price period itself\\ \\ApiInputException 10256 - if there are discounts with non-unique min_stay values for a single price period\\ \\ApiInputException 10258 - if there are discounts where the price value isn't decreasing with increasing min_stay values\\ \\PricesServiceException 12148 - if the price periods in the JSON have overlapping time periods\\ \\PermissionException 10152 - if the api key doesn't have access to all objects in the request\\ \\PermissionException 10159 - if the api key isn't allowed to create price periods for all objects in the request\\ \\PricesServiceException 12148 - if there would be overlapping time periods with existing price periods after the transaction\\ \\ApiInputException 10238 - if there is a price ID in the URL and there are more than one prices in the JSON data.\\ \\ApiJsonException 10249 - if the JSON data does not contain price IDs\\ \\ApiInputException 10239 - if there is a price ID in the URL and it does not match the ID in the JSON data.\\ \\ApiInputException 10281 - if the JSON data contains the same price ID more than once\\ \\PermissionException 10152 - if the api key isn't allowed to access the objects for these price periods\\ \\PermissionException 10159 - if the api key isn't allowed to update price periods for all objects of prices that keep their object_id\\ \\PermissionException 10159 - if the object_id is changing and the api key isn't allowed to delete price periods for the former objects\\ \\PermissionException 10159 - if the object_id is changing and the api key isn't allowed to create price periods for the future objects\\ \\ApiInputException 10280 - if a price ID doesn't exist\\ \\PermissionException 10159 - if the api key isn't allowed to delete the price periods for their objects\\ \\ ---- ===== B. Price settings (per property) ===== This service is a subservice and enables you to set all additional pricing information related to an entire property. ==== Additional prices ==== Additional prices are property related and do not differ from season to season. That is, there is no possibility to provide altering prices for e.g. the final cleaning for different periods. The following additional prices can be set: * Final cleaning * Booking fee * Linen * Towels * Breakfast * High chair * Pets * Cot * Sauna * Solarium * Laundry package (linen and towels) * Custom (Enter any additional service) Additional prices can have different units (per stay, per person and stay, per person and night, per night, per unit, per unit and night). Not all combinations make sense of course, so choose wisely. =) ==== Short stay surcharge ==== If you want to charge an extra fee for short stays, you can do so using this parameter. You can set the extra fee and choose a frequency (per night, per stay, per person, per person and night). Please note that the length of your short stay surcharge has to be at least as long as your lowest minimum stay of any of your season. If you have a min stay of 7 nights and set your short stay surcharge to six, bookings will not be possible. ==== Extra person surcharge ==== You can indicate whether or not your provided prices refer to the entire unit or only to a certain amount of guest. Assuming your property sleeps four people in total and your prices only relate to two guest, you must set an extra fee per night for each extra person. Setting a fee of 10€ will consequently raise the rate by 20 € per night. ==== Service methods ==== This subservice only supports two methods (GET and PUT). Use PUT to create, update and delete additional prices. ^ Method ^ URL ^ Description ^ | GET |/service/prices/object/$object_id |Show all additional prices for a specific property | | PUT |/service/prices/object/$object_id | Insert, update or delete all additional prices for a specific property | See JSON scheme for further details [[api:services:schemata:prices#additional_prices_scheme_prices_per_property|Additional prices scheme (prices per property)]] === Example PUT request === [json] { "guests": { "basis": 2, "surcharge": 10 }, "short_stays": { "max_nights": 6, "frequency": "per person", "price": 5 }, "services": [ { "type": "bed linen", "obligation": "optional", "frequency": "per person", "price": 20 }, { "type": "booking fee", "obligation": "compulsory", "frequency": "once", "price": 15 }, { "type": "final cleaning", "obligation": "inclusive", "frequency": "once" }, { "type": "custom", "custom": "Other", "obligation": "optional", "frequency": "per unit", "price": 5 }, { "type": "towels", "obligation": "optional", "frequency": "per person", "price": 10 }, { "type": "pets", "obligation": "optional", "frequency": "per unit", "price": 7.5 } ] } [/json] Example response: [json] { "OK": 1, "Request": { "Method": "PUT", "Path": "/service/prices/object/1010397" }, "PricesObjectServiceResult": { "guests": { "basis": 2, "surcharge": 10 }, "short_stays": { "max_nights": 6, "frequency": "per person", "price": 5 }, "services": [ { "type": "bed linen", "obligation": "optional", "frequency": "per person", "price": 20 }, { "type": "booking fee", "obligation": "compulsory", "frequency": "once", "price": 15 }, { "type": "final cleaning", "obligation": "inclusive", "frequency": "once" }, { "type": "custom", "custom": "Other", "obligation": "optional", "frequency": "per unit", "price": 5 }, { "type": "towels", "obligation": "optional", "frequency": "per person", "price": 10 }, { "type": "pets", "obligation": "optional", "frequency": "per unit", "price": 7.5 } ] } } [/json] Tips: * Make sure to ALWAYS include ALL additional prices while sending JSON documents. That is, if you want to update only one specific add-on and omit the others, all other add-ons be deleted. * Please always double-check your settings by using GET to show current status. ==== Error Codes ==== \\ApiInputException 10237 - if the URL does not contain an ID\\ \\PermissionException 10152 - if the api key isn't allowed to access the object\\ \\PermissionException 10159 - if the api key isn't allowed to retrieve object-related price informations for the object\\ \\ApiMethodException always\\ \\ApiInputException 10237 - if the URL does not contain an ID\\ \\ApiJsonException 10241 - if the HTTP body contains invalid JSON\\ \\ApiJsonException 10249 - if the JSON data is violating the JSON Schema of this Service\\ \\ApiJsonException 10249 - if guests.basis is != 0 and guests.surcharge isn't given\\ \\ApiJsonException 10249 - if services[$i].custom isn't given when services[$i].type = 'custom'\\ \\ApiJsonException 10249 - if services[$i].price isn't given when services[$i].obligation is 'compulsory' or 'optional'\\ \\PricesServiceException 12077 - if service[$i].obligation = 'inclusive' and service[$i].price is present\\ \\PricesServiceException 12896 - if no service with type 'final cleaning' is given\\ \\ApiInputException 10281 - if services[$i].type with type != 'custom' is not unique\\ \\ApiInputException 10281 - if services[$i].custom is not unique\\ \\PermissionException 10152 - if the api key isn't allowed to access the object\\ \\PermissionException 10159 - if the api key isn't allowed to update object-related price informations for the object in the URL\\ \\ApiInputException 10274 - if guests.basis is not below the maximum possible guests count for this object\\ \\ApiMethodException always\\ \\ ---- ===== C. Testing prices ===== For your convenience we have developed a sub-service that lets you test the price settings you have made by returning the final rental price for a specific property, date range and additional services. ^ Method ^ URL ^ Description ^ | POST |/service/prices/calculate/ |Calculate prices for a specific property | See JSON scheme for further details [[api:services:schemata:prices#testing_prices|Testing prices]] === Example POST request === [json] { "object_id": 1010397, "arrival": "2017-01-21", "departure": "2017-01-28", "guests": 4, "services": { "towels": 1, "pets": 2 } } [/json] Example response: [json] { "OK": 1, "Request": { "Method": "POST", "Path": "/service/prices/calculate/" }, "PricesCalculateServiceResult": { "OK": 1, "Request": { "object_id": 1010397, "arrival": "2017-01-21", "departure": "2017-01-28", "guests": 4, "services": { "towels": 1, "pets": 2 } }, "Result": { "total_price": 924, "price_per_night": 132, "nights": 7, "services": { "booking fee": 1, "towels": 4, "pets": 2, "final cleaning": 1 } } } } [/json] Tips: * This example refers to the property used in all previous requests, especially the one submitting the additional prices * All optional additional prices with units "per stay", "per person", "per night" and "per person/night" have to be "activated" by submitting a "1" because these prices are being determined by the length of stay and the amount of persons automatically. Consider it to be a checkbox! The actual amount used is being returned to you within the response. (E.g. "towels") * Cumpolsory prices are being calculated/included automatically, such as the "booking fee" or the "final cleaning". Likewise, the actual amount used is being returned. * Additional prices with units "per unit" and "per unit/night" have to be submitted with the actual amount you would like to use. (E.g. "pets") ==== Error Codes ==== \\ApiMethodException always\\ \\ApiMethodException 10056 - if the URL contains an entity id\\ \\ApiJsonException 10241 - if the HTTP body contains invalid JSON\\ \\ApiJsonException 10249 - if the JSON data is violating the JSON Schema of this Service\\ \\ApiJsonException 10249 - if the request contains a service without a name (PHP JSON Schema insufficiency)\\ \\ApiInputException 10227 - if the arrival date is after the departure date\\ \\ApiInputException 10226 - if the departure date is in the past\\ \\ApiInputException 10274 - if guests is above the maximum possible guests count for this object\\ \\PricesServiceException 12249 - if the services object in the JSON uses a service that isn't defined for the object\\ \\ApiInputException 10274 - if a service without a per unit frequency has an amount greater than one\\ \\ApiMethodException always\\ \\ApiMethodException always\\ \\ ---- ===== D. Further price settings (not yet supported) ===== Our pricing system is not yet capable of handling prices for children but will be in the near future. Besides, prices for on-the-spot services will also be implemented shortly. \\ ---- ===== E. Booking rules ===== Booking rules support landlords in renting out their properties seamlessly and conveniently to maximize bookings and occupancy. Most rules apply to directly bookable properties only, some are relevant for all types of properties. The following rules are available: ==== Minimum stay ==== You are of course able to set your preferred arrival and departure days. They may vary from season to season. Please make sure to choose at least one each otherwise your property cannot be booked. ==== Arrival and departure days ==== You can set every combination of arrival and departure days per season. For example, only allow arrivals on Saturdays and Sundays in summer and on any weekday for the winter season. Please make sure to set at least one. Omitting this field will activate all. ==== Dependent minimum gap ==== This option guarantees a consecutive booking is only being made right on the departure day of a previous booking OR after a minimum gap (mostly set to the length of the minimum stay) to prevent gaps that cant be sold any more. This way you can ensure seamless bookings. ==== Mandatory minimum gap (days between bookings) ==== If you inevitably need a fixed gap between bookings to prepare the property for following guests, set this option to “1” or “2”. ==== Days to arrival ==== If you do not want to be taken by surprise, activate this option. Guest will only be able to book a certain amount of time in advance before their arrival. Booking and arriving on the same day will be disallowed. ==== Deactivate minimum stay for gaps ==== If you happen to have a "booking gap" that is shorter than your minimum length of stay, you are able to still allow bookings for this gap using this option. However, only bookings that would entirely close this gap are possible. Arrival and departure day rules are still being adhered to but can be suspended with the option "Deactivate arrival and departure days for gaps". Example: YOu have a minimum stay of seven nights and for some reason there is a gap in between two bookings of five nights, activating this option allows guest to book these five nights regardless of your usual minimum stay. ==== Deactivate arrival and departure days for gaps ==== This option only works in combination with "Deactivate minimum stay for gaps" and adds the possibility to allow gap bookings even if your standard arrival and departure days would prevent it. If your constellation of bookings wouldn't allow a booking to be made according to your arrival and departure days, you can deactivate this rule to still receive a booking and sell your vacancies. Example: Assuming one reservation ends on Sunday and your following booking starts on Saturday, you wouldn't be able to sell these six nights in case you have set your arrival days to saturdays only. Deactivating arrival day rules will then result in the possibility to book from Sunday to Saturday. These booking rules have been implemented primarly for those properties that can be booked online. If you send bookings rules for properties with "direct owner contact", only minimum stays and arrival/departure days will impact price calculations and booking possibilities.