Extras

Extras are up-sell items that can be added to unit items

To use this capability add octo/extras to your Octo-Capabilities header.

Extras are up-sell items that can be added to unit items. An example of an extra could be a "Lunch Package" or a "Fast Track Entrance".

Product Extras

GET https://api.ventrata.com/octo/products/:id

Extra items must be purchased within a unit item, therefore a list of available extras will be contained within the unit object, like so:

{
  // rest of the unit object
  "extras": [
    {
      "id": "12d7eb39-da3b-4b09-ac3d-a2e55f12e4a4",
      "internalName": "Fast Track Entrance",
      "title": "Fast Track Entrance",
      "description": "Skip the queue and get to the front of the line saving as much as 2 hours.",
      "reference": "FAST-123",
      "restrictions": {
        "minQuantity": 1,
        "maxQuantity": 1
      },
      "pricingFrom": [
        {
          "original": 800,
          "retail": 600,
          "net": 450,
          "currency": "USD",
          "currencyPrecision": 2,
          "includedTaxes": []
        }
      ]
    }
  ]
}

The example above includes the octo/pricing and octo/content capabilities which will add the pricing and pricingFrom keys to the response. The values will be identical to the pricing fields on unit so read the documentation on the pricing capability to learn more.

FieldDescription

id

The ID of the extra

internalName

The internal name of the extra

title

The public title of the extra. This is provided by the octo/content capability.

description

The public description of the extra. This is provided by the octo/content capability.

reference

The internal reference/SKU

restrictions.minQuantity

The minimum quantity that can be bought of this extra per unit item.

restrictions.maxQuantity

The maximum quantity that can be bought of this extra per unit item. If this value is 1 then it can only be bought once per unit item.

pricingFrom / pricing

These fields come from the octo/pricing capability. Read the documentation on the pricing capability to learn what these fields mean.

Extras don't require vacancies and aren't affected by availability, so any extra you see on the product can be purchased without needing to check availability.

Extra Availability

POST https://api.ventrata.com/octo/availability

Extras themselves don't require availability as they belong to units that do, however you may find it helpful to query extras as part of an availability request to get total pricing. For example:

{
  "localDateStart": "2023-01-01",
  "localDateEnd": "2023-02-01",
  "productId": "225e4ae3-ab6f-49d0-8b35-e1df53d5ce20",
  "optionId": "DEFAULT",
  "units": [
    {
      "id": "adult",
      "quantity": 2,
      "extras": [
        {
          "id": "12d7eb39-da3b-4b09-ac3d-a2e55f12e4a4",
          "quantity": 2
        }
      ]
    }
  ]
}

Which shows how 2 adult tickets with 2 extras are queried. When used with the pricing capability this would result in the following:

[
  {
    "id": "2023-03-20T00:00:00-04:00",
    "localDateTimeStart": "2023-03-20T00:00:00-04:00",
    "localDateTimeEnd": "2023-03-20T18:00:00-04:00",
    "allDay": true,
    "available": true,
    "status": "FREESALE",
    "vacancies": null,
    "capacity": null,
    "paxCount": 18,
    "maxUnits": null,
    "maxPaxCount": null,
    "utcCutoffAt": "2023-03-20T22:00:00Z",
    "openingHours": [
      {
        "from": "09:00",
        "to": "18:00"
      }
    ],
    "unitPricing": [
      {
        "unitId": "adult",
        "original": 1000,
        "retail": 450,
        "net": 360,
        "currency": "USD",
        "currencyPrecision": 2,
        "includedTaxes": [
          {
            "name": "Sales Tax",
            "original": 48,
            "retail": 21,
            "net": 17
          }
        ],
        "extraPricing": [
          {
            "extraId": "12d7eb39-da3b-4b09-ac3d-a2e55f12e4a4",
            "original": 50,
            "retail": 22,
            "net": 22,
            "currency": "USD",
            "currencyPrecision": 2,
            "includedTaxes": [
              {
                "name": "Sales Tax",
                "original": 2,
                "retail": 1,
                "net": 1
              }
            ]
          }
        ]
      }
    ],
    "pricing": {
      "original": 2100,
      "retail": 944,
      "net": 764,
      "includedTaxes": [
        {
          "name": "Sales Tax",
          "retail": 44,
          "net": 36,
          "original": 100
        }
      ],
      "currency": "USD",
      "currencyPrecision": 2
    }
  }
]

Booking Reservation

POST https://api.ventrata.com/octo/bookings

{
  //..rest of the unit item object
  "extraItems": [
    {
      "uuid": "6f5364b4-f29e-4b17-8544-679ee643a606",
      "extraId": "12d7eb39-da3b-4b09-ac3d-a2e55f12e4a4",
      "resellerReference": "TEST-31242"
    }
  ]
}

The uuid and resellerReference fields are optional and you can include as many extras (even the same extra more than once - if it's allowed) to the unit item.

The unit item object will contain the extraItems array which will look like this:

{
  // The rest of the unit item object
  "extraItems": [
    {
      "uuid": "6f5364b4-f29e-4b17-8544-679ee643a606",
      "resellerReference": "TEST-31242",
      "supplierReference": "G7PCF6",
      "extraId": "12d7eb39-da3b-4b09-ac3d-a2e55f12e4a4",
      "extra": {
        "id": "12d7eb39-da3b-4b09-ac3d-a2e55f12e4a4",
        "internalName": "Fast Track Entrance",
        "title": "Fast Track Entrance",
        "description": "Skip the queue and get to the front of the line saving as much as 2 hours.",
        "reference": "FAST-123",
        "restrictions": {
          "minQuantity": 1,
          "maxQuantity": 1
        }
      },
      "pricing": {
        "original": 800,
        "retail": 600,
        "net": 450,
        "currency": "USD",
        "currencyPrecision": 2,
        "includedTaxes": []
      }
    }
  ]
}

When using the octo/pricing capability, the pricing of the unit item will always include the sum of the extra items that it has.

Last updated