# Item deliveries

When [ordering items](/digital-platform/orders/ordering-items), the client may also indicate when and where the items should be delivered. This is done by
providing one or more `itemDeliveries` and assigning them to individual items.

The following item delivery methods are supported:

- In-seat delivery - items are delivered to a seat during a showtime.
- Custom location delivery - items are immediately delivered to a custom location (e.g., a table).
- Electronic delivery - items are delivered electronically (e.g., a digital voucher or gift card).
- Service area pickup - items are delivered to a service area for pickup by the patron.
- Counter pickup - items are picked up from POS by the patron.


Clients must inspect the `allowedDeliveryMethods` property of an item to determine which delivery methods are
available.

Item deliveries may have an associated [item delivery fee](/digital-platform/orders/standard-orders/item-delivery-fees).

NOTE
Available delivery methods are limited based on whether an item requires preparation.

## In-seat deliveries

When creating an in-seat item delivery, the `showtimeId` and `seats` properties must be provided. These details
are typically sourced from:

- Showtimes within in-progress [ticket orders](/digital-platform/orders/standard-orders#ticket-orders).
- [Completed orders](/digital-platform/completed-orders) that contains tickets or in-seat deliveries.
- QR codes displayed at physical seats.


In-seat deliveries can be prepared immediately via the `Immediate` schedule or at a specific time via the `ShowtimeDeliveryWindow` schedule.

### Showtime delivery windows

When specifying an `ShowtimeDeliveryWindow` preparation schedule, the `showtimeDeliveryWindowId` must be
provided.

Use the [GetItemProfileForSite](/openapi/digital-platform/openapi/items/ocapiitemprofiles_getitemprofileforsite/) endpoint to get the available showtime delivery windows for a site.

```json
{
  "itemProfile": {
    "siteId": "0000000003",
    "itemShowtimeDeliveryWindows": [
      {
        "minutes": 10,
        "type": "MinutesFromStart",
        "id": "0000000003-FirstService",
        "name": {
          "text": "First Service - 10 mins"
        }
      },
      {
        "minutes": 45,
        "type": "MinutesFromStart",
        "id": "0000000003-SecondService",
        "name": {
          "text": "Second Service - 45 mins"
        }
      }
    ]
  }
}
```

NOTE
Some properties have been omitted from the code snippet above for brevity.

## Postal deliveries

When creating a postal delivery, the `postalDeliveryMethodId` property must be provided, to indicate which delivery
method to use, e.g. standard vs express shipping. Delivery methods supported by the gift shop can be sourced from the
[gift shop item profile](/openapi/digital-platform/openapi/items/ocapiitemprofiles_getitemprofileforgiftshop).

```json
{
  "itemProfile": {
    "itemPostalDeliveryMethods": [
      {
        "id": "1002-0000000001",
        "name": {
          "text": "1 Day Courier",
          "translations": []
        },
        "isDefault": true,
        "deliveryFee": {
          "type": "FixedPrice",
          "price": {
            "valueIncludingTax": 10.0,
            "valueExcludingTax": 8.64,
            "tax": 0.86
          }
        }
      },
      {
        "id": "1002-0000000002",
        "name": {
          "text": "3 Day Courier",
          "translations": []
        },
        "isDefault": false,
        "deliveryFee": {
          "type": "FixedPrice",
          "price": {
            "valueIncludingTax": 5.0,
            "valueExcludingTax": 4.33,
            "tax": 0.43
          }
        }
      }
    ]
  }
}
```

Customer postal address details must be set via the [SetCustomer](/openapi/digital-platform/openapi/orders/ocapiordercustomer_setcustomer)
endpoint after creating the postal delivery.

Postal deliveries do not support scheduled delivery.

NOTE
Postal deliveries are only available for [gift shop orders](/digital-platform/orders/gift-shop-orders) and are limited to one postal
delivery per order.

## Service area pickups

When creating a service area pickup, no additional information is required as the service areas are back-end
configuration and cannot be defined by the client.

The schedule of a service area pickup can be set to `Immediate` or `OnRequest`.

NOTE
Items that require preparation and have no delivery assigned by the client will be assigned a `ServiceAreaPickup`
delivery with the `OnRequest` schedule.

For convenience, the `serviceAreaPickupSchedule` request property on the
[SetItems](/openapi/digital-platform/openapi/items/ocapiorderitems_setitems/) endpoint can be used to control
which type of schedule will be applied to default service area pick up deliveries.

```json
{
  "items": [
    {
      "itemId": "0002-001"
    },
    {
      "itemId": "0002-002"
    }
  ],
  "serviceAreaPickupSchedule": {
    "type": "Immediate"
  }
}
```

IMPORTANT
Note that the `serviceAreaPickupSchedule` request property is only applicable for Standard Orders.

## Delivery comments

Item deliveries that require preparation allow for `comments` to be provided. Delivery comments can be used to offer
free-text additional requests that go beyond system-defined item modifiers and options.

## Requesting preparation

Item deliveries with an `OnRequest` schedule require the patron to request preparation after the order has been completed.

See [item delivery preparation](/digital-platform/completed-orders/item-delivery-preparation) for more info.