Promotions / Offers
Adds the ability to use offer codes and have combination discounts
To use this capability add ventrata/offers to your Octo-Capabilities header.
The offers capability depends on octo/pricing and if you want to make use of combination discounts you will also need ventrata/cart.
The offers capability gives the ability for promotion codes to be applied to the booking. It also provides "comparisons" which are alternative products the guest can upgrade to, and "combinations" which are related products the the customer can purchase at a discount.
Get Available Offers
POST https://api.ventrata.com/octo/availability
It's possible for the supplier to create public offers which will apply by default to new bookings if they qualify the offer's criteria. These will be returned on the availability check response.
Request Body
offerCode
string
The offer code you want to use
productId
string
The product id
optionId
string
The option id
localDateStart
string
Start date to query for (YYYY-MM-DD)
localDateEnd
string
Inclusive end date to query for (YYYY-MM-DD)
units[].id
string
The unit id
units[].quantity
integer
The quantity of the unit
[
{
//...rest of the availability object
"offers": [
{
"code": "promotion/983972a2-84e9-4506-8c84-fb2885f6375b",
"title": "10% OFF",
"description": "Winter Special 10% off",
"rateAdjustment": "COMMISSION",
"restrictions": {
"minUnits": 0,
"maxUnits": null,
"minTotal": 0,
"maxTotal": null,
"unitIds": [
"adult",
"youth",
"child"
]
}
}
]
}
]The availability response will have a new key offers added to each availability object which will include an array of available offers. For example:
[
{
//...rest of the availability object
"offerCode": "promotion/983972a2-84e9-4506-8c84-fb2885f6375b",
"offerTitle": "10% OFF",
"offers": [
{
"code": "promotion/983972a2-84e9-4506-8c84-fb2885f6375b",
"title": "10% OFF",
"description": "Winter Special 10% off",
"netDiscount": "COMMISSION",
"restrictions": {
"minUnits": 0,
"maxUnits": null,
"minTotal": 0,
"maxTotal": null,
"unitIds": [
"adult",
"youth",
"child"
]
}
}
]
}
]We will automatically apply the first available offer when requesting availability and when making a booking, but you're able to pick a different offer from the list by using the offers[].code value in offerCode parameter either when making a booking or when querying availability. The offer fields are described below:
Field
Description
code
The offer code
title
A description of how much the discount is for
description
A description of what this offer is for and how it can be used
netDiscount
Will this offer also discount your net rate and if so by how much, possible values are:
NONE The net rate will stay the same, so you will pay for the discount out of your commission. It only affects the retail rate.
FULL The offer discount will be deducted from the net rate and you'll receive your full commission as if you had sold the booking at full price.
SPLIT The discount amount will be split 50/50 between you and the supplier. If the discount amount was $10 then the net rate will be reduced by $5.
PRO_RATA The discount amount will be split proportionally between you and the supplier. So if the booking retail was $50, net rate was $40 and discount was $5, then the net rate would be reduced by $4.
restrictions[minUnits]
The minimum number of unit items needed to be bought to use this offer.
restrictions[maxUnits]
The maximum number of unit items allowed to be bought with this offer. Null means unlimited.
restrictions[minTotal]
The minimum retail amount of the whole booking needed to use this offer.
restrictions[maxTotal]
The maximum retail amount for the whole booking allowed to be bought with this offer. Null means unlimited.
restrictions[unitIds]
The Unit IDs this promotion applies to.
Discount Booking
PATCH https://api.ventrata.com/octo/bookings/:uuid
This is the booking update endpoint, except we provide the offerCode.
Path Parameters
:uuid
string
The UUID of the booking
Request Body
offerCode
string
The promotion code
// ..rest of the booking object
"pricing": {
"original": 8800,
"retail": 7400,
"net": 5500,
"currency": "EUR",
"includedTaxes": [
{
"name": "VAT 10",
"retail": 674,
"net": 452
}
]
},
"offerCode": "20CE",
"offerTitle": "20% OFF",The only new additions to the booking object are detailed below:
// ..rest of the booking object
"pricing": {
"original": 8800,
"retail": 7400,
"net": 5500,
"currency": "EUR",
"includedTaxes": [
{
"name": "VAT 10",
"retail": 674,
"net": 452
}
]
},
"offerCode": "20CE",
"offerTitle": "20% OFF",The value of original will be the price before the discount was applied. The value of offerCode will be the code used and offerTitle will be the name of the offer if you want to display it somewhere.
Product Comparisons
GET https://api.ventrata.com/octo/bookings/:uuid
Comparisons are alternative products the customer may want to upgrade their booking to.
Path Parameters
:uuid
string
The UUID of the booking
// ..rest of the booking object
"offerComparisons": [
{
"productId": "8d7519d2-cac2-4daa-8aab-d9f97265e495",
"optionId": "c0b29b9d-0540-4bb4-8034-6e93cd95d6e8",
"pricing": {
"original": 9600,
"retail": 9600,
"net": 7500,
"currency": "EUR",
"includedTaxes": [
{
"name": "VAT 10",
"retail": 874,
"net": 825
}
]
}
}
]This capability will add the following fields to the booking object:
// ..rest of the booking object
"offerComparisons": [
{
"productId": "8d7519d2-cac2-4daa-8aab-d9f97265e495",
"optionId": "c0b29b9d-0540-4bb4-8034-6e93cd95d6e8",
"pricing": {
"original": 9600,
"retail": 9600,
"net": 6700,
"currency": "EUR",
"includedTaxes": [
{
"name": "VAT 10",
"retail": 874,
"net": 782
}
]
}
}
]These are meant to be an array of comparable products that you can upgrade the booking too. The pricing object on the comparison is the cost of the equivalent booking if it were upgraded.
To upgrade the booking you simply perform a booking update request:
{
"productId": "8d7519d2-cac2-4daa-8aab-d9f97265e495",
"optionId": "c0b29b9d-0540-4bb4-8034-6e93cd95d6e8"
}Product Combinations
GET https://api.ventrata.com/octo/orders/:orderId
Combinations are related products that the customer may be interested in. They are often offered with a discount if purchased together. This endpoint is only available with the octo/cart capability.
Path Parameters
:orderId
string
The order ID
{
"id": "55460013-641c-4642-9c85-8b7acc81902b",
"status": "ON_HOLD",
"bookings": [ ... ],
"pricing": {
"original": 8800,
"retail": 8800,
"net": 7200,
"currency": "EUR",
"includedTaxes": [
{
"name": "VAT 10",
"retail": 800,
"net": 782
}
]
},
"offerCombinations": [
{
"productId": "bb4fb601-ee1e-4af6-a1e5-32f08f22a8ec",
"optionId": "DEFAULT",
"offerCode": "combination+4bd3e625-b056-4ce1-a194-6563f4a9a3f5",
"offerTitle": "€10 OFF",
"pricing": {
"original": 7100,
"retail": 6100,
"net": 5500,
"currency": "EUR",
"includedTaxes": [
{
"name": "VAT 10",
"retail": 610,
"net": 562
}
]
}
}
]
}The main addition here from the order object is the offerCombinations field which looks like this:
"offerCombinations": [
{
"productId": "bb4fb601-ee1e-4af6-a1e5-32f08f22a8ec",
"optionId": "DEFAULT",
"offerCode": "combination+4bd3e625-b056-4ce1-a194-6563f4a9a3f5",
"offerTitle": "€10 OFF",
"pricing": {
"original": 7100,
"retail": 6100,
"net": 5500,
"currency": "EUR",
"includedTaxes": [
{
"name": "VAT 10",
"retail": 610,
"net": 520
}
]
}
}
]The array is a list of all the availability combinations. To add one of the combination options to cart you first have to query the availability
Last updated
Was this helpful?