Q137: How to set up a custom pricing scheme?

Note: this is an advanced topic not directly supported by checkin24-7's interface and requiring programming skills.

checkin24-7's Pricing Manager supports a vast range of pricing models that include seasonal pricing and discounts depending on a number of conditions (see this question for more info).

If this doesn't fit your pricing model, you can specify a completely custom pricing scheme in form of an external script located on your web server that will return the price based on the input parameters passed to your script by checkin24-7, such as rental start/end time, number of persons, number of resources rented and resource ID.

If you're not a developer, we can write the script for you. In exchange we ask you to credit your own checkin24-7 account with a one-time payment of EUR 150 for simple scripts or more for more complex ones. Then, we'll need you to send us the exact specification of your pricing structure. So, this way we write this script for you free of charge if you continue using our service.

To use a custom pricing scheme, instead of specifying price in resource settings (you can also do this in the Default price rule in Pricing Manager), specify the URL of your script (e.g. http://yoursite.com/scriptname.php). Please note that further Pricing Manager rules (after Default price) will not be applied when custom script is used. The following parameters are sent (POST method):

• start (int) -- start time (sent as timestamp, that is the number of seconds since January 1 1970 00:00:00)
• end (int) -- end time (sent as timestamp)
• persons (int) -- number of persons
• resource (int) -- id of the resource to be rented
• count (int) -- number of resources selected
• units (int) -- number of time units for rental
• The script also receives all additional reservation data (depending on which data is specified for given resource). For example, if you added to the reservation form a check box 'Airport transfer' it would be passed as the parameter 'Airport_transfer'. Note that space and other non-alphanumerical characters are replaced with underscore. Checkboxes, if selected, will have the value: on (no value otherwise).
• user (int) - ID of the user who's making the reservation (passed only when possible to extract user ID based on the email address, if already entered into the form)
• user_xxx - all user-specific properties are passed to the script with the user_ prefix
• site_xxx - all site properties are passed to the script with the site_ prefix
• prop_res_xxx - all resource-specific properties are passed to the script with the prop_res_xxx prefix
• zip (string) - contains user's zip code
• country (string) - user's country 2-letter code (ISO 3166), e.g. US for the USA, DE for Germany
• language (string) - 2-letter code (ISO 639-1) of the language used by the customer
• voucher_discount (string) - discount to be applied by the script to the calculated price based on the voucher code used; this will never be set if you don't use vouchers. This can be in form: X, Y% or X+Y% depending on how you use vouchers
• voucher (string) - voucher code used (if any)
• prev-res (string) - this parameter contains all reservations from the same user for given month (plus previous month) in form of semi-colon separated objects. A single object is in turn a comma-separated list containing the following items: start_time_timestamp(int), end_time_timestamp(int), resource_id(int), quantity(int), status(int)
• existing_rental_id (int), existing_rental_creation (int) - if the pricing script is calculating the price of a reservation which already has an ID, the reservation id and creation time (as a timestamp) are passed here
• shopping_cart_id (int) - ID of the shopping cart if the pricing script is called to calculate the price of a reservation already in user's shopping cart. checkin24-7 will call the pricing script again after each new item is added to the shopping cart so you can apply a discount based on other cart items
• shopping_cart_items (string) - comma separated list of all reservation IDs in the user's shopping cart
• admin_mode - set to 1 if it's the administrator or moderator who is entering the reservation, 0 otherwise

There are three possibilities with respect to what the script returns:

• To indicate that the resource can be rented: return a simple amount (float) such as "10.00" or "105.80" without any other content. The amount should be the gross price (incl. taxes if any).
• If you want an error message to be displayed to the client, the script should return the text Error: followed by your error message. This is very useful if you want to specify custom unavailability rules (e.g. on weekends reservations must be for min. 2 hours)
• The script can also return complex information about the price, in form of a JSON-encoded array. This array should contain the following keys:
  • can_reserve: true or false depending on whether the customer should be able to make the reservation
  • price: gross price (incl taxes)
  • regular_price: in case a voucher or another discount was used, you can specify the regular price which the customer would have payed without the voucher discount. This is used for example to indicate the discount on the invoice. You can skip this field or set it to the same value as price in case no voucher was used.
  • info_text: you can specify HTML code to be displayed under the price. This can be a price breakdown or any other information you wish to show to the customer. You can apply basic formatting, e.g. add a SPAN tag with a class attribute. This key can be skipped.
  • error_text: if can_reserve is set to false, this field should include the error message (reason why reservation is not possible).
  • deposit: you can override the default deposit amount (set in resource properties) by specifying it here. This way the deposit (pre-payment amount) can depend on any specific data passed to the script
  • pricing_custom_properties: you can optionally return custom properties as a named array in this key. These values will be saved and you'll be able to view them in the reservation details (admins only), you will also be able to use them in invoices and other templates using the $(prop_xxx) tag (see FAQ Q204).
  Here's an example of a JSON array which could be returned:
  

  {"price":15,"regular_price":15,"info_text":"<span>3 days @ $5.00 = $15.00</span>","can_reserve":true,"error_text":null,"deposit":1.53}

  
  

Here's a sample PHP script that can calculate a different price for weekly and daily rentals as well as for different seasons:

< ?php
// date/time functions will work fine with timezone set to GMT
date_default_timezone_set (GMT);

// sample seasons and pricing here
define ('HIGH_SEASON_MONTH_START', 7); // first month of high season (without discount)
define ('HIGH_SEASON_MONTH_END', 9); // last month of high season (without discount)
define ('LOW_SEASON_DISCOUNT', 20); // discount in %
define ('WEEKLY_PRICE', 100); // price for a week in EUR
define ('DAILY_PRICE', 20); // price per day in EUR

function get_param ($name) {
        global $_GET; // let's check GET parameters as well for testing purposes
        global $_POST; // parameters are sent by checkin24-7 using POST
        if (isset ($_GET [$name]))
                return $_GET [$name];
        return $_POST [$name];
}

// parameters passed by checkin24-7
$units = get_param ('units'); // number of time units
$count = get_param ('count'); // number of resources
$start_date_stamp = get_param ('start'); // start date
$end_date_stamp = get_param ('end'); // end date
$persons = get_param ('persons'); // number of persons
$resource = get_param ('resource'); // resource id

// start date
$start_date = getdate ($start_date_stamp);
$month = $start_date ['mon'];

// season-based discount
if ($month < HIGH_SEASON_MONTH_START || $month > HIGH_SEASON_MONTH_END)
        $discount_factor = 100 - LOW_SEASON_DISCOUNT;
else
        $discount_factor = 100;

// use weekly or daily price
if ($units >= 7) {
        $weeks = ceil ($units / 7);
        $price = $weeks * WEEKLY_PRICE * $discount_factor / 100;
}
else {
        $price = $units * DAILY_PRICE * $discount_factor / 100;
}

echo $price;

? >

You can test/debug your pricing script by going to http://www.checkin24-7.com/reserve-test.php (you need to be logged in first). Here you can enter your custom pricing URL, choose the dates and under the price shown you can click on the link 'Price URL used'. This will give you the exact parameters passed by checkin24-7 to your script for given input parameters (start/end time, number of persons etc.).