Promocode API v1 (Accommodations) User Guide

The Promocode API can be used to make OpenGDS interact with your own voucher database. If your company relies on (promo)codes for guests to create reservations, this is the way to go.
Promocodes can be used to give access and/or discounts to specific rates.

Info: When combining the Promocode API with promocodes created in OpenGDS, the promocodes in OpenGDS are given priority.
OpenGDS will first check the promocodes in OpenGDS, when the promocode is not found, the Promocode API is used to check your database for the promocode.

The Promocode API has two calls, check and redeem. For both calls your can enter different endpoints, but this may also be the same URL.

Note: The Promocode check URL and Promocode redeem URL must be secured with HTTP Basic authentication over TLS.

You have for example endpoint "https://mydomain.com/api/promocode/check.php" for Promocode check URL. The basic PHP for check.php can look like this:

<?php

header('Content-Type: application/json; charset=UTF-8');

$response = [];
if (($promocode = findPromocode($_POST['promocode'])) !== null) {
    $response = [
        'rate_interface_id' => $promocode['offer_id'],
        'valid_till' => $promocode['expire_date']
    ];
}
if ($response) {
    echo json_encode($response);
} else {
    http_response_code(404);
}

Info: OpenGDS requests will be of Content-Type: application/x-www-form-urlencoded; charset=UTF-8.
The endpoints must return a UTF-8 JSON response, Content-Type: application/json; charset=UTF-8.

Check request (POST)

Parameter	Presence	Description
promocode	Always	The promocode OpenGDS wants to check. Format: string (max. 20 characters)

Response

{
    "rate_interface_id": "6535253",
    "valid_from": "2026-04-01",
    "valid_till": "2026-11-10",
    "valid_from_arrival": "2026-05-10",
    "valid_till_arrival": "2026-12-31",
    "exclude_arrivals": ["2026-07-14", "2026-07-15", "2026-08-20"],
    "type": "discount",
    "discount_type": "pr",
    "currency_code": "USD",
    "discount_rate": "19.95",
    "discount_rate_type": 0,
    "description": "Promocode description",
    "view_description": true,
    "disable_rate_discount": true,
    "multi_accom": false,
    "agent_rate": "89.99",
    "meta_fields": {
        "contract_number": 65434587,
        "cms_title": "Non refundable rate"
    }
}

JSON element	Necessity	Description
rate_interface_id	Mandatory	The Rate Interface IDs valid for the promocode. Format: string or array
valid_from	Optional	From this date, the promocode can be used to make a reservation. Format: YYYY-MM-DD (with leading zeros) Default: The current date
valid_till	Optional	Until this date, the promocodes can be used to make a reservation. The promocode is valid up to and including the valid_till date. Format: YYYY-MM-DD (with leading zeros) Default: No end date
valid_from_arrival	Optional	This is the first arrival day guests can choose, when making a reservation with the promocode. Format: YYYY-MM-DD (with leading zeros) Default: The current date
valid_till_arrival	Optional	This is the last arrival day guests can choose, when making a reservation with the promocode. Arrivals are possible up to and including the valid_till_arrival date. Format: YYYY-MM-DD (with leading zeros) Default: No end date
exclude_arrivals	Optional	Arrival days that guests cannot choose when making a reservation with the promocode. Format: Array containing one or multiple dates as YYYY-MM-DD (with leading zeros) Maximum: 50 dates
type	Optional	"access" or "discount" Default: "access"
discount_type	Mandatory, when {"type": "discount"}	How the discount is calculated, possible values are: "pd" => Per day "pn" => Per night "pp" => Per person "pa" => Per accommodation "pr" => Per reservation
currency_code	Optional, only applicable when {"type": "discount", "discount_rate_type": 0}	Which currency is used for the discount_rate value. Format: Three-letter uppercase currency code according to ISO-4217. Default: The currency of the user group connected to the API key used for requesting the Core API.
discount_rate	Mandatory, when {"type": "discount"}	The actual discount rate. Format: number as string
discount_rate_type	Optional, only applicable when {"type": "discount", "discount_type": "pa"} or {"type": "discount", "discount_type": "pr"}	The type of the discount_rate, possible values are: 0 => Fixed rate (Default) 1 => Percentage
description	Optional	Description of the promocode. Can be used for log and debug purposes or in combination with view_description. Format: string
view_description	Optional	Show the description in the confirmation email and include it in the core API. The latter can be used to show the description in the reservation module (for example in the receipt). Format: true or false (boolean) Default: false
disable_rate_discount	Optional	Disable other discounts on the rate (like long stay, early booking or last minute discounts). Format: true or false (boolean) Default: false
multi_accom	Optional	Allow reservations with multiple accommodations. Format: true or false (boolean) Default: false
agent_rate	Optional	When the property receives a dynamic rate (for example, the highest bid from an auction website), the agent_rate can be used to inject the rate for the booked accommodation through the Channel Manager. The agent_rate must be provided in the currency of the property. Also see Rate injection in the Rates guide of OpenGDS. Format: number as string
meta_fields	Optional	Additional meta fields for the promocode. Format: JSON object Must be a single-dimensional object. Use underscores for the spaces in the field names. This way field names can be converted to readable names. Use English as field name language, many field names will be automatically translated when needed. These fields will not be visible to the guest.

Info: For non-existent or already redeemed promocodes, your server can return HTTP status code 404, 410 or 422.

Note: Successful check responses will be cached for 15 minutes to garantee continuity and fast responses. After redemption the cache for the specific promocode is immediately released.

 

Redeem request (POST)

Parameter	Presence	Description
promocode	Always	The promocode OpenGDS wants to redeem. Format: string
res_id	Always	The ID of the created reservation (reservation number). Format: integer
property_interface_id	When the booked property has an Interface ID.	The Interface ID of the booked property. Format: string
trace_code	When a trace_code is provided with the Core API Create reservation request.	The given trace code to identify the reservation. Format: string

Response

{
    "success": true
}

JSON element	Necessity	Description
success	Mandatory	The success status of the redemption, possible values are: true => The redemption was successful false => The redemption failed, OpenGDS will NOT try again

Info: If OpenGDS does not receive a HTTP status code 200 with a valid JSON response, OpenGDS will retry to redeem the promocode multiple times. If the redemption continues to fail, you will receive an email notification.

Tip: Check the API log for troubleshooting. Also check the log on a regular basis to see if any errors occurred.