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

Name	Type	Description
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

200

[
  {
    //...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

Name	Type	Description
:uuid	string	The UUID of the booking

Request Body

Name	Type	Description
offerCode	string	The promotion code

200

// ..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

{ "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.

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

Name	Type	Description
:uuid	string	The UUID of the booking

200

// ..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"
}

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

Name	Type	Description
:orderId	string	The order ID

200

{
  "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