Comment on page


Redeem tickets and bookings by reference or barcode
To use this capability add octo/redemption to your Octo-Capabilities header.
This capability allows a supplier to redeem tickets using a barcode or reference number. It's not enabled by default and not available or intended for resellers.
You can see a full description of the endpoint and documentation on each field here.
The response is an array of bookings, the schema of which is described here. The only addition are two fields:
redemptionCode which you'll need to redeem that booking. redeemable which is true or false depending whether this booking can be redeemed.
The first thing to note is the endpoint may return multiple results, when this happens it is because the scanned code might be that of a package which contains more than one bookings that you must chose which you want to redeem.
Note if your application groups multiple redemption codes together it's also possible to send redemptionCode parameter as an array of codes you want to redeem. If this parameter is sent as an array then the response body will also be an array of each redemption response. For example:
POST /redemption/redeem HTTP/1.1
Content-Type: application/json
Authorization: Bearer 5bd1629a-323e-4edb-ac9b-327ef51e6136
"redemptionCode": [
Will redeem codes "a", "b" and "c" together.
The redemptionCode parameter is taken from the lookup response. The response will return the booking object, now with a status altered to "REDEEMED".
Redemption Credentials
An example request might be like:
POST /redemption/credentials HTTP/1.1
Content-Type: application/json
"reference": "HTA89203",
"apiKeys": [
The system will then search through each API key to find the one most appropriate for the given code and return it, for example:
{ "apiKey": "5bd1629a-323e-4edb-ac9b-327ef51e6136" }
However if the code is not recognised from any of the apiKeys then null will be returned instead, for example:
{ "apiKey": null }
In which case you should assume the reference does not belong to any of the provided apiKeys.
Redemption Validation
Finally the POST /redemption/validate endpoint allows you to validate a ticket against the validation rules stored in our system. Use this if you want to rely on our system to define the validation rules beyond redemption and not have to manage the validity state yourself.
Note if the ticket is not already redeemed the validate endpoint will automatically redeem it first, so it's suggested that you you should use either redemption/redeem or redemption/validate but not both at the same time.
Last modified 4mo ago