Creating a reservation temporarily holds an offer, guaranteeing its availability and price for a limited time.
To create the reservation, you can use the POST /v1/booking/reservations/_bulk endpoint by passing the following JSON body:
{
"items": [
{
"quantity": 1,
"offer": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894",
"ticketSessions": [
{
"ticket": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894/tickets/0194ac40-fda7-78c1-8fcb-26fc2e2612d4"
},
{
"ticket": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894/tickets/7522b8de-37a2-458d-b099-6d515b0739be",
"session": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894/tickets/7522b8de-37a2-458d-b099-6d515b0739be/sessions/337177bc-e513-444f-bcee-49a3e25b48a3"
}
]
}
]
}For the first ticket there is no session to choose we just need to pass the ticket iri.
For the second ticket we choose the session 337177bc-e513-444f-bcee-49a3e25b48a3 that occurs at 2025-06-07T20:00:00+02:00.
curl --request POST \
--url https://api.demo.korusticket.com/v1/booking/reservations/_bulk \
-H 'accept: application/ld+json' \
-H 'Authorization: Bearer {{YOUR_JWT_TOKEN}}' \
-H 'Accept-Language: fr' \
-d '{"items":[{"quantity":1,"offer":"/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894","ticketSessions":[{"ticket":"/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894/tickets/0194ac40-fda7-78c1-8fcb-26fc2e2612d4"},{"ticket":"/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894/tickets/7522b8de-37a2-458d-b099-6d515b0739be","session":"/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894/tickets/7522b8de-37a2-458d-b099-6d515b0739be/sessions/337177bc-e513-444f-bcee-49a3e25b48a3"}]}]}'{
"@context": {
"@vocab": "https://api.demo.korusticket.com/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#",
"reservations": "CreateReservationBulkOutput/reservations",
"failedReservations": "CreateReservationBulkOutput/failedReservations"
},
"@type": "CreateReservationBulkOutput",
"@id": "/.well-known/genid/78651cc4640b9253b7c0",
"reservations": [
{
"@id": "/v1/booking/reservations/35e72d9b-0fdc-44e3-869c-e1781c14418e",
"@type": "BookingReservation",
"expired": false,
"id": "35e72d9b-0fdc-44e3-869c-e1781c14418e",
"createdAt": "2025-01-29T07:55:53+00:00",
"totalAmountInclTax": "80.00",
"totalAmountExclTax": "75.83",
"expiresAt": "2025-01-29T08:10:53+00:00",
"items": [
{
"@type": "ReservationItem",
"@id": "/.well-known/genid/dbb1fda993fdc977bbab",
"unitAmountInclTax": "80.00",
"unitAmountExclTax": "75.83",
"offer": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894",
"product": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/products/0194abfe-1c04-7ade-9bc3-dbcfefb12652",
"offerTickets": [
{
"@type": "ReservationItemOfferTicket",
"@id": "/.well-known/genid/6fef51eaef68c943a2de",
"ticket": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894/tickets/0194ac40-fda7-78c1-8fcb-26fc2e2612d4"
},
{
"@type": "ReservationItemOfferTicket",
"@id": "/.well-known/genid/567f51eaef68c943aaa",
"ticket": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894/tickets/7522b8de-37a2-458d-b099-6d515b0739be",
"session": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894/tickets/7522b8de-37a2-458d-b099-6d515b0739be/sessions/337177bc-e513-444f-bcee-49a3e25b48a3"
}
]
}
],
"organization": "/v1/ticketing/organizations/0194abdc-3a79-7ec3-b1b9-a1f291de587d",
"order": null
}
],
"failedReservations": []
}The response contains two arrays :
- the
“reservations”array contains the successful reservations - the
"failedReservations"array contains offers that failed to be reserved
The "expiresAt" indicates when the reservation expires. After this timestamp, the offer will be released and the reservation will become invalid for booking.
To finalize the booking, call the POST /v1/booking/orders/_bulk endpoint. This converts reservations into actual bookings in the ticket issuer's system. Make this call only after confirming that the customer's payment was successful.
To create the order, call the endpoint with the previously created reservation IDs and customer information. You must also include your own reference ID in the optional "externalReference" field (max length 255 characters).
{
"reservations": [
"/v1/booking/reservations/0194b10f-3ddd-70a5-a96a-d1026cd42746"
],
"customer": {
"firstname": "John",
"lastname": "Doe",
"email": "[email protected]",
"phone": "0612345678",
"country": "FR",
"language": "fr"
},
"externalReference": "CUSTOM_BOOKING_REF_NUMBER_003"
}Execute the request as follows:
url --request POST \
--url https://api.demo.korusticket.com/v1/booking/orders/_bulk? \
-H 'accept: application/ld+json' \
-H 'Authorization: Bearer {{YOUR_JWT_TOKEN}}' \
-d '{"reservations":["/v1/booking/reservations/0194b10f-3ddd-70a5-a96a-d1026cd42746"],"customer":{"firstname":"John","lastname":"Doe","email":"[email protected]","phone":"0612345678","country":"FR","language":"fr"}}'{
"@context": {
"@vocab": "https://api.demo.korusticket.com/docs.jsonld#",
"hydra": "http://www.w3.org/ns/hydra/core#",
"orders": "CreateOrderBulkOutput/orders"
},
"@type": "CreateOrderBulkOutput",
"@id": "/.well-known/genid/ca4347e0ca0909425dee",
"orders": [
{
"@id": "/v1/booking/orders/0194b132-448c-7d1b-bb13-f8e09ae5c18f",
"@type": "BookingOrder",
"id": "0194b132-448c-7d1b-bb13-f8e09ae5c18f",
"createdAt": "2025-01-29T08:34:09+00:00",
"organization": "/v1/organizations/0194abdc-3a79-7ec3-b1b9-a1f291de587d",
"reference": "KT-ORD-6799E80128885",
"externalReference": "CUSTOM_BOOKING_REF_NUMBER_003",
"totalAmountInclTax": "80.00",
"totalAmountExclTax": "75.83",
"reservation": "/v1/booking/reservations/0194b10f-3ddd-70a5-a96a-d1026cd42746",
"customer": [],
"items": [
{
"@type": "OrderItem",
"@id": "/.well-known/genid/fc26307a17a3ad7720bc",
"unitAmountInclTax": "80.00",
"unitAmountExclTax": "75.83",
"product": "/v1/ticketing/catalogs/0194d07e-aa37-7171-820c-712e91552451/products/0194abfe-1bdb-7b12-af59-ad81ae443689",
"tickets": [
{
"@type": "ReservationItemOfferTicket",
"@id": "/.well-known/genid/6fef51eaef68c943a2de",
"ticket": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894/tickets/0194ac40-fda7-78c1-8fcb-26fc2e2612d4",
"voucher": null,
"occursAt": null,
"requiredBeneficiaryFields": [],
"beneficiary": null,
"beneficiaryDesignationDeadline": null,
"beneficiaryAmendable": true,
"status": "validated",
"seating": null
},
{
"@type": "ReservationItemOfferTicket",
"@id": "/.well-known/genid/567f51eaef68c943aaa",
"ticket": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894/tickets/7522b8de-37a2-458d-b099-6d515b0739be",
"voucher": "8553501100013199",
"occursAt": "2025-06-07T20:00:00+02:00",
"requiredBeneficiaryFields": [],
"beneficiary": null,
"beneficiaryDesignationDeadline": "2025-12-31T18:30:00+01:00",
"beneficiaryAmendable": true,
"status": "validated",
"seating": {
"@type": "TicketSeating",
"@id": "/.well-known/genid/af3f16442024ed4d37cb",
"seatNumber": "227",
"level": "EST/INT-127-128-129-130-131",
"row": "26",
"stand": "EST",
"stair": "131",
"gate": "V"
}
}
]
}
],
"documents": [
"/v1/booking/orders/0194b132-448c-7d1b-bb13-f8e09ae5c18f/documents/0194b132-449c-79cd-9da1-50be439b6e9d"
]
}
]
}In the response you can see the following fields:
"reference"is the Korus Ticket API internal order reference“externalReference”is your own order reference. You can call the POST v1/booking/orders/_bulk endpoint multiple times with the same value in the“externalReference”field to group all orders in the same booking."items”contains the detail of reserved products and their prices as well as tickets and associated sessions“documents”lists the available order documents. These are typically the customer's tickets for the Event. You will need to call the PATCH /v1/booking/orders/{orderId}/documents endpoint to get the document's public URL.
If one or more reservations passed to the POST v1/booking/orders/_bulk endpoint are expired, you will get an HTTP 422 response with the following violations:
{
"@context": "/contexts/ConstraintViolationList",
"@id": "/validation_errors/d53a91b0-def3-426a-83d7-269da7ab4200",
"@type": "ConstraintViolationList",
"status": 422,
"violations": [
{
"propertyPath": "reservations[0].expired",
"message": "La réservation a expiré",
"code": "d53a91b0-def3-426a-83d7-269da7ab4200"
}
],
"detail": "reservations[0].expired: La réservation a expiré",
"description": "reservations[0].expired: La réservation a expiré",
"type": "/validation_errors/d53a91b0-def3-426a-83d7-269da7ab4200",
"title": "An error occurred"
}To access orders documents, including events tickets, please refer to this section.