# 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="" 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="" 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="" 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="" 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="" 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="" 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](https://docs.ventrata.com/octo-core/products#list-products)). {% openapi src="" 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="" 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="" 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="" 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="" 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="" 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](https://docs.ventrata.com/octo-core/bookings#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" ] } } ] } ```