search
Ventrata.comOCTO.travel
githubEdit

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.

All paths below are under /octo.

hashtag
Endpoints

Gift voucher routes are documented below.

hashtag
Create Gift

post

Create a gift with offerCode.

Body
amountnumber · floatOptional

Amount numeric value.

Example: 220
currencystringOptional

ISO 4217 currency code.

Example: USD
messagestringOptional

Message value.

Example: Request accepted for asynchronous processing.
resellerReferencestringOptional

Reseller reference value.

Example: RES-BOOK-10045
uuidstringOptional

User-submitted UUID field that can be used to uniquely reference this resource and provide idempotency against repeat requests with the same UUID.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2
termsAcceptedbooleanOptional

From capability octo/content.

Example: true
offerCodestringOptional

From capability octo/offers.

Example: SUMMER25
orderIdstringOptional

From capability octo/cart.

Example: ord_20260514_9f3c21
returnUrlstring · uriOptional

From capability octo/cardPayments.

Example: https://checkout.city-sightseeing.com/return
identityIdstring · nullableOptional

From capability octo/identities.

Example: identity_customer_001
Responses
chevron-right
200

Successful response

application/json
post
/gifts
200

Successful response

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 gift object without duplicating the gift voucher.

The gift voucher object returned by all gift endpoints in this section is also used in order responses under gifts[].

hashtag
Update Gift

patch

Update a gift with offerCode.

Path parameters
uuidstringRequired

User-submitted UUID field that can be used to uniquely reference this resource and provide idempotency against repeat requests with the same UUID.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2
Body
amountnumber · floatOptional

Amount numeric value.

Example: 220
currencystringOptional

ISO 4217 currency code.

Example: USD
messagestringOptional

Message value.

Example: Request accepted for asynchronous processing.
resellerReferencestringOptional

Reseller reference value.

Example: RES-BOOK-10045
uuidstringOptional

User-submitted UUID field that can be used to uniquely reference this resource and provide idempotency against repeat requests with the same UUID.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2
termsAcceptedbooleanOptional

From capability octo/content.

Example: true
offerCodestringOptional

From capability octo/offers.

Example: SUMMER25
orderIdstringOptional

From capability octo/cart.

Example: ord_20260514_9f3c21
returnUrlstring · uriOptional

From capability octo/cardPayments.

Example: https://checkout.city-sightseeing.com/return
identityIdstring · nullableOptional

From capability octo/identities.

Example: identity_customer_001
Responses
chevron-right
200

Successful response

application/json
patch
/gifts/{uuid}
200

Successful response

You can update a gift voucher before and after it has been confirmed as long as it has not been redeemed and is still updateable. To check this, use the gift.updatable field.

hashtag
Gift Offers Preview

patch

Preview gift updates with offerCode.

Path parameters
uuidstringRequired

User-submitted UUID field that can be used to uniquely reference this resource and provide idempotency against repeat requests with the same UUID.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2
Body
amountnumber · floatOptional

Amount numeric value.

Example: 220
currencystringOptional

ISO 4217 currency code.

Example: USD
messagestringOptional

Message value.

Example: Request accepted for asynchronous processing.
resellerReferencestringOptional

Reseller reference value.

Example: RES-BOOK-10045
uuidstringOptional

User-submitted UUID field that can be used to uniquely reference this resource and provide idempotency against repeat requests with the same UUID.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2
termsAcceptedbooleanOptional

From capability octo/content.

Example: true
offerCodestringOptional

From capability octo/offers.

Example: SUMMER25
orderIdstringOptional

From capability octo/cart.

Example: ord_20260514_9f3c21
returnUrlstring · uriOptional

From capability octo/cardPayments.

Example: https://checkout.city-sightseeing.com/return
identityIdstring · nullableOptional

From capability octo/identities.

Example: identity_customer_001
Responses
chevron-right
200

Successful response

application/json
patch
/gifts/{uuid}/preview
200

Successful response

hashtag
Gift Offers Confirmation

post

Confirm an existing gift with offerCode.

Path parameters
uuidstringRequired

User-submitted UUID field that can be used to uniquely reference this resource and provide idempotency against repeat requests with the same UUID.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2
Body
amountnumber · floatOptional

Amount numeric value.

Example: 220
currencystringOptional

ISO 4217 currency code.

Example: USD
messagestringOptional

Message value.

Example: Request accepted for asynchronous processing.
resellerReferencestringOptional

Reseller reference value.

Example: RES-BOOK-10045
uuidstringOptional

User-submitted UUID field that can be used to uniquely reference this resource and provide idempotency against repeat requests with the same UUID.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2
termsAcceptedbooleanOptional

From capability octo/content.

Example: true
offerCodestringOptional

From capability octo/offers.

Example: SUMMER25
orderIdstringOptional

From capability octo/cart.

Example: ord_20260514_9f3c21
returnUrlstring · uriOptional

From capability octo/cardPayments.

Example: https://checkout.city-sightseeing.com/return
identityIdstring · nullableOptional

From capability octo/identities.

Example: identity_customer_001
Responses
chevron-right
200

Successful response

application/json
post
/gifts/{uuid}/confirm
200

Successful response

See the confirmation operation above for request examples.

Once the gift is confirmed and deliverable, voucher delivery options are populated on the response.

The deliveryValue for QRCODE can be typed online to redeem the gift voucher, and URL-based formats can be shared directly with the guest.

hashtag
Delete Gift

delete

Cancel a gift voucher.

Path parameters
uuidstringRequired

User-submitted UUID field that can be used to uniquely reference this resource and provide idempotency against repeat requests with the same UUID.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2
Query parameters
reasonstringOptional

Cancellation reason. If not a known enum value, source stores this as cancellation notes with reason other.

Example: Customer request
forcebooleanOptional

Force cancellation when allowed by cancellation rules.

Example: true
Body
amountnumber · floatOptional

Amount numeric value.

Example: 220
currencystringOptional

ISO 4217 currency code.

Example: USD
messagestringOptional

Message value.

Example: Request accepted for asynchronous processing.
resellerReferencestringOptional

Reseller reference value.

Example: RES-BOOK-10045
uuidstringOptional

User-submitted UUID field that can be used to uniquely reference this resource and provide idempotency against repeat requests with the same UUID.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2
termsAcceptedbooleanOptional

From capability octo/content.

Example: true
offerCodestringOptional

From capability octo/offers.

Example: SUMMER25
orderIdstringOptional

From capability octo/cart.

Example: ord_20260514_9f3c21
returnUrlstring · uriOptional

From capability octo/cardPayments.

Example: https://checkout.city-sightseeing.com/return
identityIdstring · nullableOptional

From capability octo/identities.

Example: identity_customer_001
Responses
chevron-right
200

Successful response

application/json
delete
/gifts/{uuid}
200

Successful response

hashtag
Gift Cancellation (Alias)

post

Alias of DELETE /gifts/:uuid. Supports the same reason and force parameters.

Path parameters
uuidstringRequired

User-submitted UUID field that can be used to uniquely reference this resource and provide idempotency against repeat requests with the same UUID.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2
Body
reasonstringOptional

Reason for the requested action.

Example: Customer request
Responses
chevron-right
200

Successful response

application/json
post
/gifts/{uuid}/cancel
200

Successful response

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

hashtag
Extend Reservation

post

Extend an existing on-hold gift reservation.

Path parameters
uuidstringRequired

User-submitted UUID field that can be used to uniquely reference this resource and provide idempotency against repeat requests with the same UUID.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2
Body
expirationMinutesintegerOptional

Expiration minutes numeric value.

Example: 30
Responses
chevron-right
200

Successful response

application/json
post
/gifts/{uuid}/extend
200

Successful response

hashtag
Get Gift

get

This route serializes gift objects that include offer fields.

Path parameters
uuidstringRequired

User-submitted UUID field that can be used to uniquely reference this resource and provide idempotency against repeat requests with the same UUID.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2
Responses
chevron-right
200

Successful response

application/json
get
/gifts/{uuid}
200

Successful response

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

hashtag
List Gifts

get

This route serializes gift objects that include offer fields.

Query parameters
resellerReferencestringOptional

Filter by reseller reference.

Example: RES-BOOK-10045
supplierReferencestringOptional

Filter by supplier reference.

Example: SUP-BOOK-7782
utcCreatedAtStartstringOptional

UTC ISO8601 range start for created-at filter.

Example: 2026-05-14T13:00:00Z
utcCreatedAtEndstringOptional

UTC ISO8601 range end for created-at filter.

Example: 2026-05-14T15:00:00Z
utcUpdatedAtStartstringOptional

UTC ISO8601 range start for updated-at filter.

Example: 2026-05-14T13:00:00Z
utcUpdatedAtEndstringOptional

UTC ISO8601 range end for updated-at filter.

Example: 2026-05-14T15:00:00Z
contactEmailAddressstringOptional

Filter by purchaser email address.

Example: [email protected]
Responses
chevron-right
200

Successful response

application/json
get
/gifts
200

Successful response

When using this endpoint you must include one of the following filters:

  • resellerReference

  • supplierReference

  • utcCreatedAtStart and utcCreatedAtEnd

  • utcUpdatedAtStart and utcUpdatedAtEnd

  • contactEmailAddress

If no valid filter is provided the API returns GIFTS_FIELDS_REQUIRED.

Results are paginated.

hashtag
Notify Gift

post

Send gift notification email for an existing gift voucher.

Path parameters
uuidstringRequired

User-submitted UUID field that can be used to uniquely reference this resource and provide idempotency against repeat requests with the same UUID.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2
Body
campaignIdstringOptional

From capability octo/campaigns.

Example: campaign_spring_2026
useContactLanguagebooleanOptional

Whether use contact language is enabled.

Example: true
Responses
chevron-right
200

Successful response

application/json
post
/gifts/{uuid}/notify
200

Successful response

Gift voucher delivery URLs (PDF/PNG/PKPASS/Google Wallet) are returned directly in voucher.deliveryOptions.

With a confirmed gift code, redeem by adding giftPayment to booking/order/gift write requests.

giftPayment is accepted on the write flows documented in:

Request payload fields are included in the operation schema above.

If the code is valid, currency matches the order currency, and the gift card has available credit then payment is applied.

If giftPayment is present but code is omitted/blank, existing non-voided gift payment transactions on the order are voided.

Order responses include the same giftPayment object and also include gift objects under gifts[].

The gift card may have enough credit to cover the full order, in which case you can confirm immediately. Otherwise, add a card payment as well (see Card Payments).

hashtag
Schema Additions (JSON)

These are additive fragments showing only fields introduced by this capability.

hashtag
Booking

hashtag
BookingWriteRequest

hashtag
Gift

hashtag
GiftCreateRequest

hashtag
Order

hashtag
OrderCreateRequest

hashtag
OrderUpdateRequest

PreviousMulti-Booking CartNextOnline Check-in

Last updated