A gift shop order allows a patron to purchase vouchers, gift cards, merchandise, etc. from a dedicated, virtual site in the circuit, known as the 'gift shop'.
The gift shop site cannot be used to complete ticketing or food and beverage orders, and will therefore not be returned by the GetSites endpoint.
The gift shop is primarily used to sell 'electronic' items, such as e-vouchers and e-gift cards, and 'physical' items for postage, such as physical vouchers, gift cards, and merchandise.
Gift shop does not currently support package items or the ability to apply modifiers to an item.
OCAPI models an 'electronic' item as an item with only the ElectronicDelivery as the allowed item delivery method.
Example:
{
"type": "Normal",
"modifierGroups": [],
"id": "1002-93207038",
"name": {
"text": "$10 E-Gift Card",
"translations": []
},
"shortName": {
"text": "$10 E-Gift",
"translations": []
},
"description": null,
"restrictions": [],
"itemClassId": "0036",
"hopk": "",
"hoCode": "",
"isSundry": true,
"isPreparationRequired": false,
"allowedDeliveryMethods": ["ElectronicDelivery"],
"availableHoursId": null,
"barcodes": []
}OCAPI models a 'physical' item as an item with PostalDelivery as one of the allowed item delivery methods.
Example:
{
"type": "Normal",
"modifierGroups": [],
"id": "1002-93206672",
"name": {
"text": "$50 Gift Card",
"translations": []
},
"shortName": {
"text": "$50 Gift",
"translations": []
},
"description": null,
"restrictions": [],
"itemClassId": "0036",
"hopk": "93206672",
"hoCode": "9010",
"isSundry": true,
"isPreparationRequired": false,
"allowedDeliveryMethods": ["PostalDelivery"],
"availableHoursId": null,
"barcodes": []
}Physical items can be delivered using any of the postal delivery methods configured for the gift shop, such as standard or express shipping. If clients do not specify a delivery method for a physical item, the default delivery method will be used. Each postal delivery method may include a fee, such as a fixed delivery charge. Multiple physical items can be grouped under the same postal delivery, resulting in a single delivery fee charged.
See Postal Delivery for more details about this delivery type.
High level order flow for purchasing gift shop items.
Use the GetItemProfileForGiftShop endpoint to load the available gift shop items for purchase, along with the postal delivery methods associated with physical items.
Use the GetItemAvailabilitiesForGiftShop endpoint to determine what gift shop items are available, i.e. not sold out.
Use the CreateGiftShopOrder endpoint to create a gift shop purchase order
Use the SetItems endpoint to set items for to the gift shop purchase order.
Electronic item example:
POST /ocapi/v1/orders/{orderId}/items
{
"items": [
{
"id": "a0b4be41-91a1-46e4-9779-0f1783531e29",
"itemId": "1002-93207038",
"type": "Normal",
"modifierGroups": []
}
],
"itemDeliveries": []
}Physical item example:
POST /ocapi/v1/orders/{orderId}/items
{
"items": [
{
"id": "2a4c3c15-e642-4993-cf85-f690e37236c5",
"itemId": "1002-93206672",
"type": "Normal",
"deliveryId": "52341ac116b5442e8cdab188575136b1",
"modifierGroups": []
}
],
"itemDeliveries": [
{
"id": "52341ac116b5442e8cdab188575136b1",
"method": "PostalDelivery",
"postalDeliveryMethodId": "1002-0000000001"
}
]
}
Mixture of electronic and physical items example:
POST /ocapi/v1/orders/{orderId}/items
{
"items": [
{
"id": "a0b4be41-91a1-46e4-9779-0f1783531e29",
"itemId": "1002-93207038",
"type": "Normal",
"modifierGroups": []
},
{
"id": "2a4c3c15-e642-4993-cf85-f690e37236c5",
"itemId": "1002-93206672",
"type": "Normal",
"deliveryId": "52341ac116b5442e8cdab188575136b1",
"modifierGroups": []
}
],
"itemDeliveries": [
{
"id": "52341ac116b5442e8cdab188575136b1",
"method": "PostalDelivery",
"postalDeliveryMethodId": "1002-0000000001"
}
]
}
Use the SetCustomer endpoint to set customer details for the gift shop purchase order.
POST /ocapi/v1/orders/{orderId}/customer
{
"name": {
"givenName": "Joe",
"familyName": "Bloggs",
"middleName": null
},
"email": "joe.bloggs@vista.co",
"phoneNumber": "+64 21 000 0000",
"preferences": {
"languageTag": "en"
},
"taxDetails": {
"name": "",
"number": ""
},
"deliveryAddress": null,
"billingAddress": null
}If the order contains physical items with a postal delivery, the digital platform will require you to provide delivery address details as part of the request. Billing address details are optional.
Due to differences in postal delivery address formats and field requirements for each country, all delivery and billing address fields are optional. It is the integrator's responsibility to validate the required fields for the relevant countries used by the sales channel.
POST /ocapi/v1/orders/{orderId}/customer
{
"name": { "givenName": "Joe", "familyName": "Bloggs" },
"email": "joe.bloggs@vista.co",
"phoneNumber": "+64 21 000 0000",
"preferences": { "languageTag": "en-US" },
"taxDetails": { "name": "", "number": "" },
"deliveryAddress": {
"name": { "givenName": "Joe", "familyName": "Bloggs" },
"companyName": "Vista Group",
"phoneNumber": "",
"line1": "123 Example Street",
"suburb": "Auckland City",
"city": "Auckland",
"state": "",
"postCode": "1010",
"country": "NZ"
},
"billingAddress": {
"name": { "givenName": "Joe", "familyName": "Bloggs" },
"companyName": "Vista Group",
"phoneNumber": "",
"line1": "123 Example Street",
"suburb": "Auckland City",
"city": "Auckland",
"state": "",
"postCode": "1010",
"country": "NZ"
}
}Subsequent SetItems requests will remove any deliveryAddress and billingAddress customer details previously set on the order for a postal delivery. To ensure no subsequent validation errors, always set customer delivery and or billing details after making item changes to a postal delivery order.
Use the GetOrder endpoint to display the current state of the in-progress gift shop purchase order.
Use the GetCustomer endpoint to get the customer details for the gift shop purchase order.
Use the GetWebPaymentMethods endpoint to display what web payment method options are available for gift shop purchase orders.
GET /ocapi/v1/web-payment-methods?orderType=GiftShopComplete payment with embedded, redirect, or external payment method. See the payments page for details on the supported payment methods and their respective payment flows.
If the Digital Platform is configured to send emails for gift shop orders, upon completion of the order the customer will be emailed their order was successful, and if the gift shop order contained any electronically deliverable items (e.g.: e-vouchers), an additional email will be sent with these items for the customer to print or redeem online.
Use the GetCompletedOrder endpoint to get the details of the completed gift shop purchase order.
Use the GetCustomer endpoint to get the customer details of the completed gift shop purchase order.