# 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`. ## Endpoints Gift voucher routes are documented below. {% openapi src="" path="/gifts" method="post" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} 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[]`. {% openapi src="" path="/gifts/{uuid}" method="patch" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} 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. {% openapi src="" path="/gifts/{uuid}/preview" method="patch" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} {% openapi src="" path="/gifts/{uuid}/confirm" method="post" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} 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. {% openapi src="" path="/gifts/{uuid}" method="delete" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} {% openapi src="" path="/gifts/{uuid}/cancel" method="post" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} Note you can only cancel a gift voucher if `gift.cancellable` is true. {% openapi src="" path="/gifts/{uuid}/extend" method="post" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} {% openapi src="" path="/gifts/{uuid}" method="get" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} This endpoint will fetch the gift voucher with the provided UUID from the system. {% openapi src="" path="/gifts" method="get" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} 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. {% openapi src="" path="/gifts/{uuid}/notify" method="post" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} 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: * [Bookings](https://docs.ventrata.com/octo-core/bookings#endpoints) * [Multi-Booking Cart](https://docs.ventrata.com/capabilities/cart) * [Gift Vouchers](#endpoints) 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](https://docs.ventrata.com/capabilities/card-payments)). ## Schema Additions (JSON) These are additive fragments showing only fields introduced by this capability. ### `Booking` ```json { "// ...rest of booking object": "...", "giftPayment": { "giftCode": "GIFT-2026-0001", "code": "SUMMER25", "amount": 220.0, "currency": "USD" } } ``` ### `BookingWriteRequest` ```json { "// ...rest of booking write request object": "...", "giftPayment": { "code": "GIFT-2026-0001" } } ``` ### `Gift` ```json { "// ...rest of gift object": "...", "giftPayment": { "code": "GIFT-2026-0001" } } ``` ### `GiftCreateRequest` ```json { "// ...rest of gift create request object": "...", "giftPayment": { "code": "GIFT-2026-0001" } } ``` ### `Order` ```json { "// ...rest of order object": "...", "gifts": [ { "uuid": "gift_20260514_ba21f7", "status": "CONFIRMED", "currency": "USD", "id": "89fe0192-ddcd-430a-b285-e1396a4725d2" } ], "giftPayment": { "code": "GIFT-2026-0001" } } ``` ### `OrderCreateRequest` ```json { "// ...rest of order create request object": "...", "gifts": [ { "amount": 100.0, "currency": "USD" } ] } ``` ### `OrderUpdateRequest` ```json { "// ...rest of order update request object": "...", "gifts": [ { "amount": 100.0, "currency": "USD" } ] } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ventrata.com/capabilities/gift-vouchers.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.