API reference

Reservations

POST /reservations holds tickets for 15 minutes while the buyer fills in their details: request format, a response with the expiry time and what to do when seats run short.

POST/reservations · scope reservations:write

A reservation holds seats for 15 minutes while the buyer fills in their details. The step is optional, and you can create a payment straight away, but at events where tickets go fast it saves you from “the buyer filled in the form and the seats are gone”.

Request

cURL

curl -X POST https://aoa.com.ua/api/v1/reservations \
  -H "Authorization: Bearer aoa_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "a1b2c3",
    "tickets": [
      { "ticketTypeId": "clx9ticket001", "quantity": 2 }
    ]
  }'

Field	Type	Description
`eventId`	string	Event identifier. Required.
`tickets`	array	A non-empty array of items. Required.
`tickets[].ticketTypeId`	string	A ticket type from the ticket-types endpoint.
`tickets[].quantity`	integer	An integer from 1 to 20, for each type separately.

Response

JSON

{
  "data": {
    "reservationId": "rsv_Xk3mQp7vR2nT8wL5yB1zC4dA",
    "eventId": "a1b2c3",
    "expiresAt": "2026-07-30T12:49:56.789Z",
    "remaining": {
      "clx9ticket001": 61
    }
  }
}

Field	Description
`reservationId`	Pass it to /checkout to turn the reservation into a payment.
`expiresAt`	When the reservation expires. Show the buyer a timer so they understand the limit.
`remaining`	What’s left after your reservation, per ticket type.

When there aren’t enough seats

A reservation is either created in full or not at all: there are no partial reservations. If there are fewer tickets than you ask for:

JSON

{
  "error": {
    "code": "conflict",
    "message": "Залишилось лише 1 квиток"
  }
}

Get the current numbers from /availability and offer the buyer a smaller quantity. Repeating the same request unchanged makes no sense.

Reservation lifecycle

You can’t cancel a reservation manually: there’s no endpoint for it. If the buyer changes their mind, just don’t use the reservation, and the seats come back on their own after 15 minutes.
A successful /checkout with this reservation uses it up.
If the payment wasn’t created for an unrelated reason, say an invalid promo code, the reservation stays alive. Fix the data and try again with the same reservationId.

Reserve when it’s needed

A reservation takes seats away from other buyers. Create it when the buyer has already chosen tickets and is moving on to payment, not while they’re browsing events.