Tax

OCAPI supports tax-inclusive and tax-exclusive pricing for tickets, items, booking fees, and other monetary values.

Monetary values are returned as the following properties to support various tax calculations:

• valueIncludingTax : The monetary value including tax.
• valueExcludingTax : The monetary value excluding tax.
• tax : The amount of tax.

Retrieving tax for tickets and items

Tax values for tickets and items can be retrieved using the following endpoints:

• GetSellableItemByHopkForSite
• GetItemProfileForGiftShop
• GetItemProfileForSite
• GetTicketPricesForShowtime

The monetary values returned by these endpoints can be used to calculate the total tax for an order before the order is created. However, for tax-exclusive price modes, the tax values should be considered an estimated amount only, as the total tax for an order may differ due to rounding.

Tax on loyalty rewards and promotions

In some cases, a loyalty member may have a reward which will change the price of an item. Additionally, a promotion may be applied to the item, requiring tax to be recalculated.

For fixed tax rates (e.g., $1.00 for alcohol), the recalculated tax may differ significantly from the actual tax.

Promotion is calculated based on full item/ticket price and tax value from discounted price value as in the example below.

{
  "title": "Medium drink",
  "displayPriority": 3,
  "itemId": "0002-700716",
  "prices": [
    {
      "price": {
        "valueIncludingTax": 1.6,
        "valueExcludingTax": 1.38,
        "tax": 0.22
      },
      "isDefault": true,
      "restrictions": [],
      "rewardId": null,
      "discount": null,
      "discountId": null
    },
    {
      "price": {
        "valueIncludingTax": 1.12,
        "valueExcludingTax": 0.97,
        "tax": 0.15
      },
      "isDefault": false,
      "restrictions": ["MemberReward"],
      "rewardId": 5016,
      "discount": {
        "calculation": {
          "percentageOff": 30.0,
          "type": "PercentageOff"
        },
        "amountSaved": {
          "valueIncludingTax": 0.48,
          "valueExcludingTax": 0.41,
          "tax": 0.07
        }
      },
      "discountId": "0002-0000000001"
    }
  ]
}

Price modes and limitations

Promotions can be applied to prices that already include taxes, or prices that exclude taxes, depending on the cinema site's configuration in Vista.

For instance, consider a scenario where a $1.00 discount is calculated based on a tax-inclusive price, valueIncludingTax. This is the default tax calculation price mode and can be applied to tickets and items.

When a tax-exclusive price mode is enabled, the discount $1.00 will be based on the tax-exclusive price, valueExcludingTax. The tax value will be calculated in addition to the discounted price and reflected in amountSaved property.

Tax on variable-priced items

Tax information for variable-priced items is not available in the item profile. The tax will only be available once the item has been added to the order at the chosen price.

Retrieving tax for orders

When an order is populated (e.g., adding tickets or items) the tax is calculated by the cinema site for the individual order lines and the entire order. These values are returned by OCAPI and can be treated as the final tax amount.

Use the GetOrder endpoint to retrieve the tax values for an in-progress order.

{
  "order": {
    "id": "cbe9ece3fd1c4dac844d93050a372c39",
    "type": "Standard",
    "status": "InProgress",
    "totalPrice": {
      "valueIncludingTax": 1.6,
      "valueExcludingTax": 1.38,
      "tax": 0.22
    },
    "booking": {
      "mode": "Paid",
      "totalBookingFee": {
        "valueIncludingTax": 0.0,
        "valueExcludingTax": 0.0,
        "tax": 0.0
      }
    },
    "showtimes": [],
    "items": [
      {
        "id": "a1b0fd21-4275-46b5-ae08-44b0c07ada8f",
        "itemId": "0002-700716",
        "type": "Normal",
        "price": {
          "valueIncludingTax": 1.6,
          "valueExcludingTax": 1.38,
          "tax": 0.22
        },
        "amountSaved": {
          "valueIncludingTax": 0.0,
          "valueExcludingTax": 0.0,
          "tax": 0.0
        }
      }
    ],
    "amountSaved": {
      "valueIncludingTax": 0.0,
      "valueExcludingTax": 0.0,
      "tax": 0.0
    },
    "tip": {
      "amount": {
        "valueIncludingTax": 0.0,
        "valueExcludingTax": 0.0,
        "tax": 0.0
      }
    }
  }
}