# Item delivery fees

An item delivery fee is a calculated additional cost added on to item purchases.

- Item delivery fees can be calculated as either:
  - Fixed fee per delivery (e.g., $1 per delivery).
  - Percentage fee per delivery (e.g., 10% of the total item price of a delivery).
- Item delivery fees can vary by delivery method, cinema, and client.
- In-seat item delivery fees can also vary by cinema operator.
- Item delivery fees are supported for the following delivery methods:
  - Counter pickup
  - Custom location delivery
  - In-seat delivery
  - Service area pickup
- For more information on item delivery fee configuration on the Digital Platform, please contact your Vista
representative.


## Item delivery fees for an order

Item delivery fees are calculated whenever items are set against an order using the
[SetItems](/openapi/digital-platform/openapi/items/ocapiorderitems_setitems/) endpoint, and when relevant item prices are recalculated.
The order includes a `totalItemDeliveryFee` property that represents the total item delivery fee the patron is required to pay.

Each delivery within the order also has a `fee` property that represents the item delivery fee for the
individual delivery (or `null` if the delivery does not incur an item delivery fee).

```json
{
  "order": {
    "id": "4c5910d17fcc45e1baad99c19b89a9bb",
    "type": "Standard",
    "status": "InProgress",
    "totalPrice": {
      "valueIncludingTax": 5.74,
      "valueExcludingTax": 4.95,
      "tax": 0.79
    },
    "items": [
      {
        "deliveryId": "1111",
        "itemId": "0002-46",
        "id": "34ce31f5-7bb0-492f-9cf7-4914caa272e2",
        "type": "Normal",
        "price": {
          "valueIncludingTax": 5.22,
          "valueExcludingTax": 4.5,
          "tax": 0.72
        }
      }
    ],
    "itemDeliveries": [
      {
        "locationName": "Table 1",
        "schedule": {
          "type": "Immediate"
        },
        "method": "CustomLocationDelivery",
        "comment": null,
        "fee": {
          "id": "1",
          "amount": {
            "valueIncludingTax": 1.04,
            "valueExcludingTax": 0.9,
            "tax": 0.14
          },
          "refundStatus": "NotRefunded",
          "refundAvailability": {
            "isAvailable": false,
            "unavailableReason": "OrderNotCompleted"
          }
        },
        "id": "1111"
      }
    ],
    "totalItemDeliveryFee": {
      "valueIncludingTax": 1.04,
      "valueExcludingTax": 0.9,
      "tax": 0.14
    }
  }
}
```

## Item delivery fees for showtimes

In-seat item delivery fees are also returned by the
[GetShowtime](/openapi/digital-platform/openapi/showtimes/ocapishowtimes_getshowtime/) endpoint. This is essential for
clients that wish to display the item delivery fee value during item selection, before the items have been ordered.

```json
{
  "showtime": {
    "id": "0002-3083",
    "inSeatItemDeliveryFee": {
      "type": "Percentage",
      "percentage": 5.5,
      "salesTaxId": "0002-0000000002"
    }
  },
  "relatedData": {
    "salesTaxes": [
      {
        "id": "0002-0000000002",
        "level1": {
          "type": "Percentage",
          "percentage": 15.0
        },
        "level2": {
          "type": "Percentage",
          "percentage": 0.0
        },
        "level3": {
          "type": "Percentage",
          "percentage": 0.0
        },
        "level4": {
          "type": "Percentage",
          "percentage": 0.0
        }
      }
    ]
  }
}
```

Because the price and tax of a percentage item delivery fee are not known until after item selection,
the client is provided with the information needed to calculate the fee price and tax.

## Item delivery fees for sites

Item delivery fees are also returned by the
[GetItemProfileForSite](/openapi/digital-platform/openapi/items/ocapiitemprofiles_getitemprofileforsite/) endpoint. This is essential for
clients that wish to display the item delivery fee value during item selection, before the items have been ordered.

```json
{
  "itemProfile": {
    "siteId": "0002",
    "customLocationItemDeliveryFee": {
      "type": "Percentage",
      "percentage": 10.0,
      "salesTaxId": "0002-0000000002"
    },
    "counterItemPickupFee": {
      "type": "Percentage",
      "percentage": 5.25,
      "salesTaxId": "0002-0000000002"
    },
    "serviceAreaItemPickupFee": {
      "type": "FixedPrice",
      "price": {
        "valueIncludingTax": 1.0,
        "valueExcludingTax": 0.85,
        "tax": 0.15
      }
    }
  },
  "relatedData": {
    "salesTaxes": [
      {
        "id": "0002-0000000002",
        "level1": {
          "type": "Percentage",
          "percentage": 15.0
        },
        "level2": {
          "type": "Percentage",
          "percentage": 0.0
        },
        "level3": {
          "type": "Percentage",
          "percentage": 0.0
        },
        "level4": {
          "type": "Percentage",
          "percentage": 0.0
        }
      }
    ]
  }
}
```

Because the price and tax of a percentage item delivery fee are not known until after item selection,
the client is provided with the information needed to calculate the fee price and tax.