Promotions / Offers

Adds the ability to use offer codes and have combination discounts

To use this capability add octo/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 octo/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.
post
Get Available Offers
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
Response
Request
Body Parameters
productId
required
string
The product id
optionId
required
string
The option id
localDateStart
required
string
Start date to query for (YYYY-MM-DD)
localDateEnd
required
string
Inclusive end date to query for (YYYY-MM-DD)
units[].id
optional
string
The unit id
units[].quantity
optional
integer
The quantity of the unit
Response
200: OK
[
  {
    //...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
    "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 in the list both 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 when making a booking. 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.
patch
Discount Booking
https://api.ventrata.com/octo/bookings/:uuid
This is the booking update endpoint, except we provide the offerCode.
Request
Response
Request
Path Parameters
:uuid
required
string
The UUID of the booking
Body Parameters
offerCode
optional
string
The promotion code
Response
200: OK
// ..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",
400: Bad Request
{ "error": "Promotion code is invalid" }
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.
get
Product Comparisons
https://api.ventrata.com/octo/bookings/:uuid
Comparisons are alternative products the customer may want to upgrade their booking to.
Request
Response
Request
Path Parameters
:uuid
required
string
The UUID of the booking
Response
200: OK
// ..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:
PATCH https://api.ventrata.com/octo/bookings/:uuid
{
  "productId": "8d7519d2-cac2-4daa-8aab-d9f97265e495",
  "optionId": "c0b29b9d-0540-4bb4-8034-6e93cd95d6e8"
}
get
Product Combinations
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.
Request
Response
Request
Path Parameters
:orderId
required
string
The order ID
Response
200: OK
{
  "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

Capabilities - Previous

Multi-booking Cart

Next - Capabilities

Card Payments

Last updated 2 months ago

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.

Promotions / Offers

postGet Available Offers

patchDiscount Booking

getProduct Comparisons

getProduct Combinations

post
Get Available Offers

patch
Discount Booking

get
Product Comparisons

get
Product Combinations