OCTO WebsiteOpenAPI (Swagger)Become a Member

Pricing

Adds pricing fields to various endpoints

To use this capability add pricing to your Octo-Capabilities header. This capability adds pricing to most endpoints giving you advanced static and dynamic pricing capabilities.

Product Pricing

GET {host}/products/:id

Returns top-level pricing by unit on each product.

Path Parameters

Name
Type
Description

id

string

The product id, leave this out to get every product.

{
  "id": "93c335bc-07b9-4f10-84e2-3df8f2daa257",
  "internalName": "Mega Pass",
  "reference": null,
  "locale": "en",
  "timeZone": "America/Los_Angeles",
  "allowFreesale": false,
  "availabilityRequired": true,
  "availabilityType": "OPENING_HOURS",
  "deliveryFormats": [
    "PDF_URL",
    "QRCODE"
  ],
  "deliveryMethods": [
    "VOUCHER",
    "TICKET"
  ],
  "redemptionMethod": "DIGITAL",
  "options": [
    {
      "id": "6963c6a3-5d6a-4f15-924c-be2530589422",
      "default": false,
      "internalName": "Pick 3",
      "reference": null,
      "restrictions": {
        "minUnits": 0,
        "maxUnits": null
      },
      "units": [
        {
          "id": "adult",
          "internalName": "Adult",
          "reference": "adult",
          "type": "ADULT",
          "restrictions": {
            "minAge": 0,
            "maxAge": 99,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": []
          },
          "pricingFrom": [
            {
              "original": 7999,
              "retail": 7999,
              "net": null,
              "currency": "USD",
              "currencyPrecision": 2
            }
          ]
        },
        {
          "id": "child",
          "internalName": "Child",
          "reference": "child",
          "type": "CHILD",
          "restrictions": {
            "minAge": 0,
            "maxAge": 99,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": []
          },
          "pricingFrom": [
            {
              "original": 5999,
              "retail": 5999,
              "net": null,
              "currency": "USD",
              "currencyPrecision": 2
            }
          ]
        }
      ]
    },
    {
      "id": "f39bde2f-2cc0-48c1-b404-af68ce2370ae",
      "default": false,
      "internalName": "Pick 4",
      "reference": null,
      "restrictions": {
        "minUnits": 0,
        "maxUnits": null
      },
      "units": [
        {
          "id": "adult",
          "internalName": "Adult",
          "reference": "adult",
          "type": "ADULT",
          "restrictions": {
            "minAge": 0,
            "maxAge": 99,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": []
          },
          "pricingFrom": [
            {
              "original": 9999,
              "retail": 9999,
              "net": null,
              "currency": "USD",
              "currencyPrecision": 2
            }
          ]
        },
        {
          "id": "child",
          "internalName": "Child",
          "reference": "child",
          "type": "CHILD",
          "restrictions": {
            "minAge": 0,
            "maxAge": 99,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": []
          },
          "pricingFrom": [
            {
              "original": 7999,
              "retail": 7999,
              "net": null,
              "currency": "USD",
              "currencyPrecision": 2
            }
          ]
        }
      ]
    },
    {
      "id": "f996c316-7541-4cb4-a96f-4a6f08cea70a",
      "default": false,
      "internalName": "Pick 5",
      "reference": null,
      "restrictions": {
        "minUnits": 0,
        "maxUnits": null
      },
      "units": [
        {
          "id": "adult",
          "internalName": "Adult",
          "reference": "adult",
          "type": "ADULT",
          "restrictions": {
            "minAge": 0,
            "maxAge": 99,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": []
          },
          "pricingFrom": [
            {
              "original": 11499,
              "retail": 11499,
              "net": null,
              "currency": "USD",
              "currencyPrecision": 2
            }
          ]
        },
        {
          "id": "child",
          "internalName": "Child",
          "reference": "child",
          "type": "CHILD",
          "restrictions": {
            "minAge": 0,
            "maxAge": 99,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": []
          },
          "pricingFrom": [
            {
              "original": 9299,
              "retail": 9299,
              "net": null,
              "currency": "USD",
              "currencyPrecision": 2
            }
          ]
        }
      ]
    }
  ],
  "defaultCurrency": "USD",
  "availableCurrencies": [
    "USD"
  ]
}

On the response, the only changes from the original schema is on the Product object:

{
  // ...rest of Product object
  "defaultCurrency": "USD",
  "availableCurrencies": ["USD", "EUR", "GBP"],
  "pricingPer": "UNIT" // "UNIT" or "BOOKING"
}

The defaultCurrency is the default currency for this product, if you omit the currency parameter on future endpoints this is the value the reservation system will fallback to. availableCurrencies are all the possible currencies that we accept for this product.

pricingPer indicates whether the pricing is per unit (most common), or per booking. Pricing which is per booking is common for private charters or group booking products where the price is the same regardless of how many tickets are purchased.

Next, if pricingPer = "UNIT", on each Unit (adult, child, etc.) we add the following:

{
  // ...rest of the Unit object
  "pricingFrom": [
    {
      "original": 4500,
      "retail": 4500,
      "net": 3500,
      "currency": "USD",
      "currencyPrecision": 2,
      "includedTaxes": [
        {
          "name": "VAT 10",
          "retail": 800,
          "net": 500
        }
      ]
    },
    {
      "original": 4000,
      "retail": 4000,
      "net": 3000,
      "currency": "GBP",
      "currencyPrecision": 2,
      "includedTaxes": [
        {
          "name": "VAT 10",
          "retail": 700,
          "net": 400
        }
      ]
    }
    // ...etc...
  ]
}

If pricingPer = "BOOKING" then these fields will be on the Product itself instead of the Unit as the pricing applies once to the booking regardless of how many units (tickets) are purchased.

We'll produce one pricingFrom object for each currency in availableCurrencies . The meaning of each pricing field is given below:

Field

Description

original

The original price for this product which will be the same or higher than the sale amount. Use this to show a discount has been applied e.g. $10 $8.50

retail

The sale price you should charge your customers.

net

The wholesale rate the supplier will charge you for this sale.

currency

The currency.

currencyPrecision

All pricing is given in integers to avoid floating point rounding issues. e.g. USD = 2 and JPY = 0. To convert a price to decimal you should do: price / (10 ** currencyPrecision) where ** is to the power of e.g. Math.pow(10, currencyPrecision).

includedTaxes

Any taxes included in the retail and/or net price.

Throughout this capability, we'll use a convention where we'll end the object key with From to indicate this is indicative and not the final price. Make sure you communicate this also to the customer.

Pricing Calendar

POST {host}/availability/calendar

Returns pricing per day for when you're generating a calendar view.

Request Body

Name
Type
Description

currency

string

The currency to use

[
  //.. each day
  {
    "localDate": "2020-07-01",
    "status": "AVAILABLE",
    "capacity": 24,
    "openingHours": []
    "unitPricingFrom": [
      {
        "unitId": "adult",
        "original": 4500,
        "retail": 4500,
        "net": 3500,
        "currency": "USD",
        "currencyPrecision": 2
      },
      {
        "unitId": "child",
        "original": 4200,
        "retail": 4200,
        "net": 3200,
        "currency": "USD",
        "currencyPrecision": 2
      }
    ]
  }
]

The documentation above only shows the additions this capability adds to the availability calendar endpoint. See the documentation here to see the full request parameters and response object.

Each availability object is given a new unitPricingFrom field with an array of unit prices in the currency for example:

{
  "localDate": "2020-07-01",
  "status": "AVAILABLE",
  "capacity": 24,
  "openingHours": []
  "unitPricingFrom": [
    {
      "unitId": "unit_adult123",
      "original": 4500,
      "retail": 4500,
      "net": 3500,
      "currency": "USD",
      "currencyPrecision": 2,
      "includedTaxes": [
        {
          "name": "VAT 10",
          "retail": 700,
          "net": 400
        }
      ]
    },
    {
      "unitId": "unit_child321",
      "original": 4200,
      "retail": 4200,
      "net": 3200,
      "currency": "USD",
      "currencyPrecision": 2,
      "includedTaxes": [
        {
          "name": "VAT 10",
          "retail": 800,
          "net": 500
        }
      ]
    }
  ]
}

If you pass the units to the request then we'll give the total pricing for the selection under the pricingFrom field, which is also included by default if pricingPer = BOOKING as the number of units isn't needed to know what the price of the booking is. For example:

{
  "productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
  "optionId": "DEFAULT",
  "localDateStart": "2020-07-01",
  "localDateEnd": "2020-07-02",
  "units": [
    {
      "id": "unit_adult123",
      "quantity": 2
    },
    {
      "id": "unit_child321",
      "quantity": 1
    }
  ]
}

Having the pricingFrom value calculated for you makes it much easier to display a single price on each date on the calendar (assuming the guest has chosen how many units they want before you display the calendar).

If pricingPer = BOOKING then unitPricingFrom will not be provided.

Pricing Check

POST {host}/availability

Returns a final quote of the price before making a booking.

Request Body

Name
Type
Description

currency

string

The currency to use

[
  {
    "id": "2020-07-01T11:30:00-05:00",
    "localDateTimeStart": "2020-07-01T11:30:00-05:00",
    "localDateTimeEnd": "2020-07-01T23:30:00-05:00",
    "utcCutoffAt": "2020-07-01T16:30:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": [],
    "unitPricing": [
      {
        "original": 3995,
        "retail": 3995,
        "net": 2996,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "adult"
      },
      {
        "original": 1995,
        "retail": 1995,
        "net": 1496,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "child"
      }
    ],
    "pricing": {
      "original": 9985,
      "retail": 9985,
      "net": 7488,
      "currency": "USD",
      "currencyPrecision": 2
    }
  },
  {
    "id": "2020-07-01T12:00:00-05:00",
    "localDateTimeStart": "2020-07-01T12:00:00-05:00",
    "localDateTimeEnd": "2020-07-02T00:00:00-05:00",
    "utcCutoffAt": "2020-07-01T17:00:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": [],
    "unitPricing": [
      {
        "original": 3995,
        "retail": 3995,
        "net": 2996,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "adult"
      },
      {
        "original": 1995,
        "retail": 1995,
        "net": 1496,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "child"
      }
    ],
    "pricing": {
      "original": 9985,
      "retail": 9985,
      "net": 7488,
      "currencyPrecision": 2,
      "currency": "USD"
    }
  },
  {
    "id": "2020-07-01T14:30:00-05:00",
    "localDateTimeStart": "2020-07-01T14:30:00-05:00",
    "localDateTimeEnd": "2020-07-02T02:30:00-05:00",
    "utcCutoffAt": "2020-07-01T19:00:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": [],
    "unitPricing": [
      {
        "original": 3995,
        "retail": 3995,
        "net": 2996,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "adult"
      },
      {
        "original": 1995,
        "retail": 1995,
        "net": 1496,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "child"
      }
    ],
    "pricing": {
      "original": 9985,
      "retail": 9985,
      "net": 7488,
      "currency": "USD",
      "currencyPrecision": 2
    }
  },
  {
    "id": "2020-07-01T15:00:00-05:00",
    "localDateTimeStart": "2020-07-01T15:00:00-05:00",
    "localDateTimeEnd": "2020-07-02T03:00:00-05:00",
    "utcCutoffAt": "2020-07-01T20:00:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": [],
    "unitPricing": [
      {
        "original": 3995,
        "retail": 3995,
        "net": 2996,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "adult"
      },
      {
        "original": 1995,
        "retail": 1995,
        "net": 1496,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "child"
      }
    ],
    "pricing": {
      "original": 9985,
      "retail": 9985,
      "net": 7488,
      "currency": "USD",
      "currencyPrecision": 2
    }
  },
  {
    "id": "2020-07-01T10:30:00-05:00",
    "localDateTimeStart": "2020-07-01T10:30:00-05:00",
    "localDateTimeEnd": "2020-07-01T22:30:00-05:00",
    "utcCutoffAt": "2020-07-01T15:30:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": [],
    "unitPricing": [
      {
        "original": 3995,
        "retail": 3995,
        "net": 2996,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "adult"
      },
      {
        "original": 1995,
        "retail": 1995,
        "net": 1496,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "child"
      }
    ],
    "pricing": {
      "original": 9985,
      "retail": 9985,
      "net": 7488,
      "currency": "USD",
      "currencyPrecision": 2
    }
  },
  {
    "id": "2020-07-01T13:30:00-05:00",
    "localDateTimeStart": "2020-07-01T13:30:00-05:00",
    "localDateTimeEnd": "2020-07-02T01:30:00-05:00",
    "utcCutoffAt": "2020-07-01T15:30:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": [],
    "unitPricing": [
      {
        "original": 3995,
        "retail": 3995,
        "net": 2996,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "adult"
      },
      {
        "original": 1995,
        "retail": 1995,
        "net": 1496,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "child"
      }
    ],
    "pricing": {
      "original": 9985,
      "retail": 9985,
      "net": 7488,
      "currency": "USD",
      "currencyPrecision": 2
    }
  },
  {
    "id": "2020-07-01T09:30:00-05:00",
    "localDateTimeStart": "2020-07-01T09:30:00-05:00",
    "localDateTimeEnd": "2020-07-01T21:30:00-05:00",
    "utcCutoffAt": "2020-07-01T14:30:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": [],
    "unitPricing": [
      {
        "original": 3995,
        "retail": 3995,
        "net": 2996,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "adult"
      },
      {
        "original": 1995,
        "retail": 1995,
        "net": 1496,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "child"
      }
    ],
    "pricing": {
      "original": 9985,
      "retail": 9985,
      "net": 7488,
      "currency": "USD",
      "currencyPrecision": 2
    }
  },
  {
    "id": "2020-07-01T12:30:00-05:00",
    "localDateTimeStart": "2020-07-01T12:30:00-05:00",
    "localDateTimeEnd": "2020-07-02T00:30:00-05:00",
    "utcCutoffAt": "2020-07-01T17:30:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "vacancies": 24,
    "capacity": 24,
    "maxUnits": 24,
    "openingHours": [],
    "unitPricing": [
      {
        "original": 3995,
        "retail": 3995,
        "net": 2996,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "adult"
      },
      {
        "original": 1995,
        "retail": 1995,
        "net": 1496,
        "currency": "USD",
        "currencyPrecision": 2,
        "unitId": "child"
      }
    ],
    "pricing": {
      "original": 9985,
      "retail": 9985,
      "net": 7488,
      "currency": "USD",
      "currencyPrecision": 2
    }
  }
]

This endpoint is the availability check endpoint which has been extended to add pricing. We only document the added parameters here, to see the full documentation for the original availability check you can find it here.

If we were to repeat the request above in the calendar section this is what the response would look like instead:

{
  "productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
  "optionId": "DEFAULT",
  "localDateStart": "2020-07-01",
  "localDateEnd": "2020-07-02",
  "units": [
    {
      "id": "unit_123abcadult",
      "quantity": 2
    },
    {
      "id": "unit_321abcchild",
      "quantity": 1
    }
  ]
}

Notice how the response fields are unitPricing and pricing (without the From suffix). That is because this is the final price, and this is what the booking will be once confirmed.

Booking Reservation

POST {host}/bookings

The booking reservation call

Request Body

Name
Type
Description

currency

string

The currency to use

{
  "uuid": "4de58057-e7bd-4ec0-be9b-08eb674098b9",
  "testMode": true,
  "resellerReference": null,
  "supplierReference": "DV2JG2",
  "status": "ON_HOLD",
  "utcExpiresAt": "2020-06-08T07:32:24Z",
  "utcConfirmedAt": null,
  "productId": "8d7519d2-cac2-4daa-8aab-d9f97265e495",
  "optionId": "23df0f5c-781a-4bee-9dae-2355bdd792c5",
  "cancellable": true,
  "cancellation": null,
  "freesale": false,
  "availability": {
    "id": "2020-06-27T00:00:00+02:00",
    "localDateTimeStart": "2020-06-27T00:00:00+02:00",
    "localDateTimeEnd": "2020-06-28T00:00:00+02:00",
    "allDay": true,
    "openingHours": []
  },
  "contact": {
    "fullName": null,
    "emailAddress": null,
    "phoneNumber": null,
    "locales": [],
    "country": null,
    "notes": null
  },
  "notes": null,
  "deliveryMethods": [
    "VOUCHER",
    "TICKET"
  ],
  "voucher": {
    "redemptionMethod": "DIGITAL",
    "utcRedeemedAt": null,
    "deliveryOptions": []
  },
  "unitItems": [
    {
      "uuid": "4c4a52cd-c0a5-49d9-b1e7-a713564993d4",
      "resellerReference": null,
      "supplierReference": "VD8KTS",
      "unitId": "unit_321abcchild",
      "ticket": {
        "redemptionMethod": "DIGITAL",
        "utcRedeemedAt": null,
        "deliveryOptions": []
      }
    },
    {
      "uuid": "8d4e198d-e337-465c-b17c-e3a55798ee97",
      "resellerReference": null,
      "supplierReference": "ENV98P",
      "unitId": "unit_123abcadult",
      "ticket": {
        "redemptionMethod": "DIGITAL",
        "utcRedeemedAt": null,
        "deliveryOptions": []
      }
    },
    {
      "uuid": "f3183108-32f4-4816-99e6-b04ae40dd433",
      "resellerReference": null,
      "supplierReference": "43FJJ4",
      "unitId": "unit_123abcadult",
      "ticket": {
        "redemptionMethod": "DIGITAL",
        "utcRedeemedAt": null,
        "deliveryOptions": []
      }
    }
  ],
  "pricing": {
    "original": 8800,
    "retail": 8800,
    "net": 5500,
    "currency": "EUR",
    "currencyPrecision": 2,
    "includedTaxes": [
      {
        "name": "VAT 10",
        "retail": 800,
        "net": 500
      }
    ]
  }
}

This capability extends the booking schema to add a pricing field which gives you the final price of the booking as well as any included taxes. The final price includes tax, and should be what you display to the guest as the amount they need to pay.

  "pricing": {
    "original": 8800,
    "retail": 8800,
    "net": 5500,
    "currency": "EUR",
    "currencyPrecision": 2,
    "includedTaxes": [
      {
        "name": "VAT 10",
        "retail": 800,
        "net": 500
      }
    ]
  }

We include the net amount as well as any taxes included in the net price.

PreviousBookingsNextNotifications

Last updated