Gift Vouchers

Allows you to sell and redeem gift vouchers
To use this capability add octo/gifts to your Octo-Capabilities header.
Gift vouchers allow you to sell fixed value monetary amounts in the form of a gift card which can be redeemed later as a form of payment against a new order.
Gift Reservation
The request above was made with the following request body:
"amount": 1000,
"currency": "USD",
"message": "Happy Birthday! Hope you enjoy your trip to Paris!",
"recipient": {
"fullName": "Oliver Morgan",
"emailAddress": "[email protected]"
The UUID on the request body is optional but recommended if you're requesting from a source of poor network connectivity. If the connection fails or you do not receive a response, you can repeat the same request with the same UUID and it will respond with the same booking object without duplicating the gift voucher.
The gift voucher object is described as:
A unique UUID used to identify the gift voucher. Make sure you save this value as you will need it to perform any future actions against this gift voucher.
Whether this gift voucher is in test mode.
Your reference (as the reseller). You set this value in the second confirmation request.
The ventrata reference for this booking. Use this to help the supplier find this booking.
The status of the gift, possible values are:
ON_HOLD The gift is pending confirmation, this is the default value when you first create the gift.
EXPIRED If the gift is not confirmed before the expiration hold expires, it goes into an expired state. CONFIRMED Once the confirmation call is made the gift is ready to be used. CANCELLED If the gift is cancelled. REDEEMED if the gift has been fully utilised
An ISO8601 date time in UTC for when this booking is due to expire if the status is ON_HOLD
An ISO8601 date time in UTC when the booking was confirmed.
The total amount of the gift card in fractional unit. So if the amount is $10.50 the amount would be 1050 for example.
The ISO 4217 currency code.
A boolean field indicating whether this booking can be cancelled.
An object with information about why and when the booking was cancelled. This is null if the booking is not cancelled.
A text value describing why the cancellation happened.
Whether the gift voucher was refunded as part of the cancellation. Possible values are FULL, PARTIAL or NONE
An ISO8601 date time in UTC indicating when the booking was cancelled.
The customer contact details. These values are set in the booking confirmation step.
The full name of the guest
The email of the guest
The phone number of the guest
An array of locale values, equivalent to navigator.languages in a browsers environment.
The customer who's intended as the recipient of this gift voucher. This is different from the contact who purchases the gift voucher.
The full name of the recipient
The email of the recipient
The phone number of the recipient
An array of locale values, equivalent to navigator.languages in a browsers environment.
A message intended for the recipient that's attached to the gift voucher.
An array of delivery methods available for this gift voucher. This is included to be consistent with the booking schema but will always be an array of one value ["VOUCHER"]
This is the gift voucher which can be given to the guest
This is to be consistent with the booking schema but the value will always be "DIGITAL"
The ISO8601 date in UTC indicating when the gift voucher was used.
This is an array of delivery options for the voucher each object. You should use one of these to give the gift voucher to the guest.
The format for the delivery option possible values are:
QRCODE You should generate the QR Code yourself and print the code below. The guest can redeem at the attraction or type the reference into the website to redeem.
PDF_URL Where we generate the PDF gift voucher which you can include on the URL.
Depending on the value of deliveryFormat this value is either:
QRCODE This value is a string to encode in a QR Code.
PDF_URL This value is a URL linking to a ventrata generated voucher PDF.
The gift voucher object schema described above will be returned on every endpoint in this section. Only the values may change.
Gift Update
You can update a gift voucher before and after it has been confirmed as long as it hasn't been redeemed or within the cancellation cutoff window. To know if the booking can be updated check the gift.cancellable field. If the gift can be cancelled, it can also be updated. It's generally preferred to update a gift rather than cancelling it and recreating it.
Gift Confirmation
An example of the confirmation request above looks like this:
"resellerReference": "VOUCHER-0123",
"contact": {
"fullName": "Oliver Morgan",
"emailAddress": "[email protected]",
"phoneNumber": "+447840739436",
"locales": ["en-GB", "en-US", "en"],
"country": "GB"
Once the gift is confirmed, the delivery options of both the voucher and/or ticket are populated. An example of the values is shown below:
//... inside the "voucher" object
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": [
"deliveryFormat": "QRCODE",
"deliveryValue": "GJ7W8FS8"
"deliveryFormat": "PDF_URL",
"deliveryValue": ""
The deliveryValue given under QRCODE can be typed online to redeem the gift voucher, alternatively the PDF can also be provided and the guest can give this to the recipient.
Gift Cancellation
Note you can only cancel a gift voucher if gift.cancellable is true.
Extend Reservation
Get Gift
This endpoint will fetch the gift voucher with the provided UUID from the system.
List Gifts
When using this endpoint you must include one of the following parameters:
  • resellerReference
  • supplierReference
The results aren't paginated as the result set will never be too long because of the required filters.
Redeem Gift Voucher
With a confirmed gift code it's possible to redeem it by adding a giftPayment field to the booking either on the reservation step or after in a PATCH /bookings/:uuid stage.
Note that if you use the octo/cart Multi-booking Cart capability then the request and response parameters are identical for the POST /orders and PATCH /orders/:id endpoints.
"giftPayment": {
"code": "GJ7W8FS8"
If the code is valid, currency matches the order currency, and the gift card is still valid with sufficient credit then it'll be applied to the booking.
A giftPayment object will then be included on the booking object response like so:
//... rest of the booking object
"giftPayment": {
"code": "GJ7W8FS8",
"amount": 700,
"currency": "USD"
It could be that the gift card has sufficient credit to cover the whole order, which case you'll be able to confirm immediately. Alternatively you may need to add a card payment also. Check out the Card Payment capability for this.
Last modified 1yr ago