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

POST https://api.ventrata.com/octo/gifts

Request Body

Name	Type	Description
uuid	string	A unique UUID to identify the gift. Setting this value acs like an idempotency key preventing you from double reservation.
expirationMinutes	integer	How many minutes to reserve the availability, otherwise defaults to the supplier default amount.
amount*	integer	The gift card amount given as the fractional amount for the gift card. E.g $10.50 is 1050
currency*	string	The ISO 4217 currency code
message	string	An optional message to send to the recipient with the gift voucher
recipient.fullName	string	The name of the person this gift voucher is for
recipient.emailAddress	string	The email of the person this gift voucher is for

200: OK

{
  "id": "d895e62d-2d51-4faa-860e-41080ed4ccca",
  "uuid": "917655fb-67b1-4d4d-84a3-0dcd3e218f9c",
  "testMode": true,
  "resellerReference": null,
  "supplierReference": "SX0Z1H",
  "status": "ON_HOLD",
  "utcCreatedAt": "2022-09-05T17:51:25Z",
  "utcUpdatedAt": "2022-09-05T17:51:25Z",
  "utcExpiresAt": "2022-09-05T18:21:25Z",
  "utcRedeemedAt": null,
  "utcConfirmedAt": null,
  "amount": 1000,
  "currency": "GBP",
  "cancellable": true,
  "cancellation": null,
  "contact": {
    "fullName": null,
    "firstName": null,
    "lastName": null,
    "emailAddress": null,
    "phoneNumber": null,
    "locales": [],
    "postalCode": null,
    "country": null,
    "notes": null
  },
  "recipient": {
    "fullName": null,
    "firstName": null,
    "lastName": null,
    "emailAddress": null,
    "phoneNumber": null,
    "locales": [],
    "postalCode": null,
    "country": null,
    "notes": null
  },
  "message": null,
  "notes": null,
  "deliveryMethods": [
    "VOUCHER"
  ],
  "voucher": {
    "redemptionMethod": "DIGITAL",
    "utcRedeemedAt": null,
    "deliveryOptions": []
  },
  "giftPayment": null
}

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.

Gift Update

PATCH https://api.ventrata.com/octo/gifts/:uuid

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

POST https://api.ventrata.com/octo/gifts/:uuid/confirm

Path Parameters

Name	Type	Description
uuid*	string	The UUID of the gift voucher

An example of the confirmation request above looks like this:

{
  "resellerReference": "VOUCHER-0123",
  "contact": {
    "fullName": "Oliver Morgan",
    "emailAddress": "[email protected]",
    "phoneNumber": "[phone]",
    "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.

Gift Cancellation

DELETE https://api.ventrata.com/octo/gifts/:uuid

Note you can only cancel a gift voucher if gift.cancellable is true.

Extend Reservation

POST https://api.ventrata.com/octo/gifts/:uuid/extend

Get Gift

GET https://api.ventrata.com/octo/gifts/:uuid

This endpoint will fetch the gift voucher with the provided UUID from the system.

List Gifts

GET https://api.ventrata.com/octo/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

POST https://api.ventrata.com/octo/bookings

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.