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.
post
https://api.ventrata.com/octo
/gifts
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:
Field
Description
uuid
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.
testMode
Whether this gift voucher is in test mode.
resellerReference
Your reference (as the reseller). You set this value in the second confirmation request.
supplierReference
The ventrata reference for this booking. Use this to help the supplier find this booking.
status
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
utcExpiresAt
An ISO8601 date time in UTC for when this booking is due to expire if the status is ON_HOLD
utcConfirmedAt
An ISO8601 date time in UTC when the booking was confirmed.
amount
The total amount of the gift card in fractional unit. So if the amount is $10.50 the amount would be 1050 for example.
currency
The ISO 4217 currency code.
cancellable
A boolean field indicating whether this booking can be cancelled.
cancellation
An object with information about why and when the booking was cancelled. This is null if the booking is not cancelled.
cancellation.reason
A text value describing why the cancellation happened.
cancellation.refund
Whether the gift voucher was refunded as part of the cancellation. Possible values are FULL, PARTIAL or NONE

cancellation.utcCancelledAt
An ISO8601 date time in UTC indicating when the booking was cancelled.
contact
The customer contact details. These values are set in the booking confirmation step.
contact.fullName
The full name of the guest
contact.emailAddress
The email of the guest
contact.phoneNumber
The phone number of the guest
contact.locales
An array of locale values, equivalent to navigator.languages in a browsers environment.
recipient
The customer who's intended as the recipient of this gift voucher. This is different from the contact who purchases the gift voucher.
recipient.fullName
The full name of the recipient
recipient.emailAddress
The email of the recipient
recipient.phoneNumber
The phone number of the recipient
recipient.locales
An array of locale values, equivalent to navigator.languages in a browsers environment.
message
A message intended for the recipient that's attached to the gift voucher.
deliveryMethods
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"]
voucher
This is the gift voucher which can be given to the guest
voucher.redemptionMethod
This is to be consistent with the booking schema but the value will always be "DIGITAL"
voucher.utcRdeemedAt
The ISO8601 date in UTC indicating when the gift voucher was used.
voucher.deliveryOptions
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.
voucher.deliveryOptions[].deliveryFormat
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.
voucher.deliveryOptions[].deliveryValue
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.
patch
https://api.ventrata.com/octo
/gifts/:uuid
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.
post
https://api.ventrata.com/octo
/gifts/:uuid/confirm
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": "https://api.ventrata.com/octo/pdf?gift=50a54a87-3fe3-4a1b-8409-15d4de0e7d41"
  }
]
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.
delete
https://api.ventrata.com/octo
/gifts/:uuid
Gift Cancellation
Note you can only cancel a gift voucher if gift.cancellable is true.
post
https://api.ventrata.com/octo
/gifts/:uuid/extend
Extend Reservation
get
https://api.ventrata.com/octo
/gifts/:uuid
Get Gift
This endpoint will fetch the gift voucher with the provided UUID from the system.
get
https://api.ventrata.com/octo
/gifts
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.
post
https://api.ventrata.com/octo
/bookings
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.

Field	Description
`uuid`	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.
`testMode`	Whether this gift voucher is in test mode.
`resellerReference`	Your reference (as the reseller). You set this value in the second confirmation request.
`supplierReference`	The ventrata reference for this booking. Use this to help the supplier find this booking.
`status`	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
`utcExpiresAt`	An ISO8601 date time in UTC for when this booking is due to expire if the status is `ON_HOLD`
`utcConfirmedAt`	An ISO8601 date time in UTC when the booking was confirmed.
`amount`	The total amount of the gift card in fractional unit. So if the amount is $10.50 the amount would be 1050 for example.
`currency`	The ISO 4217 currency code.
`cancellable`	A boolean field indicating whether this booking can be cancelled.
`cancellation`	An object with information about why and when the booking was cancelled. This is `null` if the booking is not cancelled.
`cancellation.reason`	A text value describing why the cancellation happened.
`cancellation.refund`	Whether the gift voucher was refunded as part of the cancellation. Possible values are `FULL`, `PARTIAL` or `NONE`
`cancellation.utcCancelledAt`	An ISO8601 date time in UTC indicating when the booking was cancelled.
`contact`	The customer contact details. These values are set in the booking confirmation step.
`contact.fullName`	The full name of the guest
`contact.emailAddress`	The email of the guest
`contact.phoneNumber`	The phone number of the guest
`contact.locales`	An array of locale values, equivalent to `navigator.languages` in a browsers environment.
`recipient`	The customer who's intended as the recipient of this gift voucher. This is different from the `contact` who purchases the gift voucher.
`recipient.fullName`	The full name of the recipient
`recipient.emailAddress`	The email of the recipient
`recipient.phoneNumber`	The phone number of the recipient
`recipient.locales`	An array of locale values, equivalent to `navigator.languages` in a browsers environment.
`message`	A message intended for the recipient that's attached to the gift voucher.
`deliveryMethods`	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"]`
`voucher`	This is the gift voucher which can be given to the guest
`voucher.redemptionMethod`	This is to be consistent with the booking schema but the value will always be `"DIGITAL"`
`voucher.utcRdeemedAt`	The ISO8601 date in UTC indicating when the gift voucher was used.
`voucher.deliveryOptions`	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.
`voucher.deliveryOptions[].deliveryFormat`	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.
`voucher.deliveryOptions[].deliveryValue`	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.

Last modified 8mo ago