Create reservations an orders

Bulk endpoints like POST /v1/booking/reservations/_bulk allow the creation of multiple resources in a single call. However, connections to ticketing sub-systems that act on behalf of ticket holders (Puy du Fou, Disney, etc.) can sometimes fail.

From reservation to order, Korus Ticket handles data exchanges with these ticketing sub-systems for you. In this context, it's possible that:

when calling the endpoint POST /v1/booking/reservations/_bulk, some or all offers may be successfully reserved while others may fail.
when calling the endpoint POST v1/booking/orders/_bulk, some or all reservations may be successfully ordered while others may fail.

For both the POST /v1/booking/reservations/_bulk and POST v1/booking/orders/_bulk endpoints, Korus Ticket performs an initial synchronous consistency check, which may result in an HTTP 422 validation error. If this first validation is successful, the API will return a JSON payload that lists both successful and failed items, depending on the responses from the subsystems.

Each reservation returned have their own lifecycle. For example 2 reservations both created in the same call can have different expiry date.

Example With Reservations

Reservation Request Body

{
  "items": [
    {
      "quantity": 1,
      "offer": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac3f-7bdd-7175-a275-30c8656182835",
      "ticketSessions": [
        {
          "ticket": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac3f-7bdd-7175-a275-30c8656182835/tickets/0194ac3f-7be0-7f34-aa3f-7f22e2aa6285",
          "session":"/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/events/01956fed-b4d0-7c08-97e7-dffdbfad1abf/sessions/0194abfe-158f-7c98-9c2f-fba57a0cc1a5"
        }
      ]
    },
    {
      "quantity": 2,
      "offer": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194cb39-19a5-730d-b7b3-ea3782713636",
      "ticketSessions": [
        {
          "ticket": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194cb39-19a5-730d-b7b3-ea3782713636/tickets/0194cb39-ad97-7d28-97ad-329dc2c1028c",
          "session":"/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/events/01956fed-bb97-7865-bdfe-1ee0250674e6/sessions/0194cb39-e17a-7e35-b534-68dbac45fa3f"
        }
      ]
    },
    {
      "quantity": 1,
      "offer": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194cb39-53ab-726a-8e07-2e662a4d098c",
      "ticketSessions": [
        {
          "ticket": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194cb39-53ab-726a-8e07-2e662a4d098c/tickets/0194cb39-cb89-728e-8f02-173ff7690e1a",
          "session":"/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/events/01956fed-e9a5-7a1a-98b4-db2daa272d56/sessions/0194cb39-fe93-748d-9ad4-7560ce53cdb7"
        }
      ]
    }
  ]
}

Reservation Response body

{
  "@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/0194b10f-3ddd-70a5-a96a-d1026cd42746",
      "@type": "BookingReservation",
      "expired": false,
      "id": "0194b10f-3ddd-70a5-a96a-d1026cd42746",
      "createdAt": "2025-01-29T07:55:53+00:00",
      "totalAmountInclTax": "42.32",
      "totalAmountExclTax": null,
      "expiresAt": "2025-01-29T08:10:53+00:00",
      "items": [
        {
          "@type": "ReservationItem",
          "@id": "/.well-known/genid/dbb1fda993fdc977bbab",
          "unitAmountInclTax": "42.32",
          "unitAmountExclTax": null,
          "quantity": 1,
          "totalAmountInclTax": "42.32",
          "totalAmountExclTax": null,
          "offer": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac3f-7bdd-7175-a275-30c8656182835",
          "product": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/products/0194cb74-4262-7f52-9e9e-da87b21325d2",
          "offerTickets": [
            {
              "@type": "ReservationItemOfferTicket",
              "@id": "/.well-known/genid/603f51eaef68c943a2f8",
              "ticket": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac3f-7bdd-7175-a275-30c8656182835/tickets/0194ac3f-7be0-7f34-aa3f-7f22e2aa6285",
              "session": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/events/01956fed-b4d0-7c08-97e7-dffdbfad1abf/sessions/0194abfe-158f-7c98-9c2f-fba57a0cc1a5"
            }
          ]
        }
      ],
      "organization": "/v1/organizations/0194abdc-3a79-7ec3-b1b9-a1f291de587d",
      "reference": "KT-RES-6799DF09A951C",
      "order": null
    }
  ],
  "failedReservations": [
    {
      "@type": "FailedReservation",
      "message": "experticket API error : Network issue",
      "items": [
        {
          "@type": "FailedReservationsOffer",
          "offer": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194cb39-19a5-730d-b7b3-ea3782713636",
          "product": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/products/0194cb76-2ef8-7dea-ac10-7b645e366534",
          "offerTickets": [
            {
              "@type": "FailedReservationsOfferTicket",
              "ticket": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194cb39-19a5-730d-b7b3-ea3782713636/tickets/0194cb39-ad97-7d28-97ad-329dc2c1028c",
              "session": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/events/01956fed-bb97-7865-bdfe-1ee0250674e6/sessions/0194cb39-e17a-7e35-b534-68dbac45fa3f"
            }
          ]
        }
      ]
    },
    {
      "@type": "FailedReservation",
      "message": "experticket API error : Not available",
      "items": [
        {
          "@type": "FailedReservationsOffer",
          "offer": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194cb39-53ab-726a-8e07-2e662a4d098c",
          "product": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/products/0194cb70-08f1-77a8-b5b3-a0abc73e26f2",
          "offerTickets": [
            {
              "@type": "FailedReservationsOfferTicket",
              "ticket": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194cb39-53ab-726a-8e07-2e662a4d098c/tickets/0194cb39-cb89-728e-8f02-173ff7690e1a",
              "session": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/events/01956fed-e9a5-7a1a-98b4-db2daa272d56/sessions/0194cb39-fe93-748d-9ad4-7560ce53cdb7"
            }
          ]
        }
      ]
    }
  ]
}

Example with Order

Order Request body

{
  "reservations": [
    "/v1/booking/reservations/0194b10f-3ddd-70a5-a96a-d1026cd42746",
    "/v1/booking/reservations/0194cb58-0e51-7403-8a5c-1214b8444e1b",
    "/v1/booking/reservations/0194cb58-5d0d-7ba3-8718-9ee2e6327556"
  ],
  "customer": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]",
    "phone": "0612345678",
    "country": "FR",
    "language": "fr"
  },
  "bookingReference": "CUSTOM_BOOKING_REF_NUMBER_012"
}

Order Response body

{
  "@context": {
    "@vocab": "https://api.demo.korusticket.com/docs.jsonld#",
    "hydra": "http://www.w3.org/ns/hydra/core#",
    "orders": "CreateOrderBulkOutput/reservations",
    "failedOrders": "CreateOrderBulkOutput/failedOrders"
  },
  "@type": "CreateOrderBulkOutput",
  "@id": "/.well-known/genid/78651cc4640b9253b7c0",
  "orders": [
    "/v1/booking/orders/0194b10f-3ddd-70a5-a96a-d1026cd42746",
    "/v1/booking/orders/0194cb58-0e51-7403-8a5c-1214b8444e1b"
  ],
  "failedOrders": [
    "/v1/booking/orders/0194cb58-5d0d-7ba3-8718-9ee2e6327556"
  ]
}