# Redemption To use this capability, add `octo/redemption` to your `Octo-Capabilities` header. This capability allows supplier/operator connections to look up bookings and tickets, redeem/unredeem them, and mark them as no-show by redemption code. All paths below are public `/octo` routes. The OCTO API prefix is `/octo`. ## Endpoint Summary {% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/redemption/lookup" 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 %} Lookup by `reference`, `email`, or `mobile`. {% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/redemption/redeem" 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 %} Redeem one or more redemption codes. {% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/redemption/redeem" 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 %} Cancel redemption (unredeem) for one or more redemption codes. {% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/redemption/noshow" 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 %} Mark one or more redemption codes as no-show. {% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/redemption/noshow" 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 %} Route variant currently mapped to the same action as `DELETE /redemption/redeem`. {% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/redemption/credentials" 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 %} Unauthenticated API key resolution by lookup input. Use `GET /products` to cache available product/option/unit metadata used by redemption responses (see [Products](/octo-core/products.md#list-products)). {% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/redemption/lookup" 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 %} Find matching bookings/tickets for a scanned code/reference, email, or mobile. **Query Parameters** Provide at least one of `reference`, `email`, or `mobile`. **Response** Returns `array[Redemption Object]` (see [Redemption Object](#redemption-object)). * Lookup can return multiple results for package products with redeemable inclusions. * Each result includes `redemptionCode`, `redeemable`, `unredeemableReason`, and `unredeemableReasonCode`. {% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/redemption/redeem" 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="/files/9aBZzqykFPaTU7bfbNrr" path="/redemption/redeem" 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 %} Both routes use the same request shape and response schema. **Request Body / Query Parameters** If `redemptionCode` is an array, the response is `array[Redemption Object]` in input order. Otherwise, the response is a single `Redemption Object`. When redemption is rejected as not redeemable, a `400 BAD_REQUEST` can include both `redemptionCode` and `redemptionErrorCode` in the response body. {% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/redemption/noshow" 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="/files/9aBZzqykFPaTU7bfbNrr" path="/redemption/noshow" 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 %} **Request Body / Query Parameters** `POST /redemption/noshow` returns a redemption object/object-array with no-show state (for example `status: "NO_SHOW"`, `utcNoshowedAt` set). `DELETE /redemption/noshow` is currently wired to the same controller path as `DELETE /redemption/redeem`, so behavior and response shape match cancel-redemption/unredeem. {% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/redemption/credentials" 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 %} This endpoint is unauthenticated and selects the first API key that can successfully resolve the provided lookup input. **Request Body Parameters** Provide at least one of `reference`, `email`, or `mobile`. **Response** ## Redemption Object Lookup, redeem, and no-show responses serialize via `serialize_redemption(...)`, which wraps `serialize_booking(...)` and ticket/voucher helpers. ### Top-level fields For full core object details of `product`, `option`, `availability`, and contact/user/reseller-style objects, see [Bookings](/octo-core/bookings.md#booking-reservation) and linked core schemas. ### Additional serialization notes * When a redemption code resolves at ticket level, `unitItems` is reduced to that ticket only, `voucher` is set to that ticket object, and overlapping root fields are overwritten with ticket-level values. * `serialize_item(...)` adds `scans: []` on serialized item units (for example `option.units[]` entries of type `OTHER`). ## Schema Additions (JSON) These are additive fragments showing only fields introduced by this capability. ### `BookingUnitItem` ```json { "// ...rest of booking unit item object": "...", "scans": [ { "id": "e7cc8bb4-8d1c-4848-8824-5dbedb718681", "status": "CONFIRMED", "utcScannedAt": "2026-05-14T13:00:00Z", "seller": { "id": "94cdd032-3d32-416d-b0a4-abf8b7495b8b", "name": "Morning City Tour", "reference": "REF-2026-001", "tags": [ "vip", "partner" ] } } ] } ``` --- # 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/redemption.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.