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

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

{
  "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": "ollym@me.com"
  }
}

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

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.

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

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": "ollym@me.com",
    "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.

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.

PreviousPackages NextRedemption

Last updated 2 years ago