> ## Documentation Index > Fetch the complete documentation index at: https://docs.prexsell.com/llms.txt > Use this file to discover all available pages before exploring further. # Create booking > Creates a booking for one or more passengers. Authenticated via the api-key header; data scoped to the caller's partner. Returns 201 with the booking aggregate. offer token failures: expired → 400 OFFER_EXPIRED; malformed → 400 VALIDATION_ERROR. Undeclared body fields are rejected (strict body — discovery-gated per ADR-0033 §7). ## OpenAPI ````yaml /docs/openapi/openapi.json post /v2/bookings openapi: 3.1.0 info: title: PREXSELL REST v2 version: 5.97.1 description: REST API for the PREXSELL bus booking management platform. servers: - url: https://staging.api.prexsell.com description: Staging - url: https://api.prexsell.com description: Production security: [] paths: /v2/bookings: post: tags: - Bookings summary: Create booking description: >- Creates a booking for one or more passengers. Authenticated via the api-key header; data scoped to the caller's partner. Returns 201 with the booking aggregate. offer token failures: expired → 400 OFFER_EXPIRED; malformed → 400 VALIDATION_ERROR. Undeclared body fields are rejected (strict body — discovery-gated per ADR-0033 §7). operationId: createBooking requestBody: required: true content: application/json: schema: type: object properties: offerId: type: string description: >- 20-minute offer JWT from GET /v2/offers. Applies to all passengers in this booking. example: eyJ... currency: type: string enum: - CZK - UAH - EUR - USD - PLN description: >- Ticket currency (single source: CURRENCIES). Applies to all passengers in this booking. example: UAH note: type: string description: Optional booking note. example: Window seat please passengers: type: array items: type: object properties: firstName: type: string description: First name. example: Іван lastName: type: string description: Last name. example: Петренко email: type: string format: email description: Passenger email. example: ivan@example.com phones: type: array items: type: object properties: phone: type: string description: Phone number. example: '+380501234567' messengers: type: array items: type: string description: Messenger apps. example: - Viber required: - phone description: Passenger phone. minItems: 1 description: At least one phone required. discountId: type: string description: Discount identifier to apply. prepaid: type: number description: Prepaid amount. example: 0 required: - firstName - lastName - phones description: A single passenger booking record. minItems: 1 description: One record per passenger. Minimum 1. required: - offerId - currency - passengers additionalProperties: false description: Create booking request body. responses: '201': description: Booking created. content: application/json: schema: type: object properties: data: type: object properties: booking: type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time departureDate: type: - string - 'null' format: date-time deprecated: true description: >- DEPRECATED — use `onboardingDateTime`. Misnomer for the UTC boarding instant (ADR-0049 §4 / ADR-0046 §8); retained during the expand/contract transition and removed in a later contract phase. example: '2026-06-15T03:30:00.000Z' onboardingDateTime: type: - string - 'null' format: date-time description: >- UTC boarding instant (rename of departureDate, ADR-0046 §8). Both are exposed during the expand/contract transition; clients should prefer this field. example: '2026-06-15T03:30:00.000Z' status: type: string enum: - Upcoming - Boarding - InTransit - Completed - Canceled description: >- Derived booking status (Upcoming | Boarding | InTransit | Completed | Canceled). Derived from the actor's partner-filtered orders and booking.departureDate. example: Upcoming bookingRequiredBy: type: - string - 'null' format: date-time description: >- Deadline by which an active Unpaid ticket must be finalized by BOOKING it (ISO 8601). Same value as paymentRequiredBy — an Unpaid ticket is finalized by booking OR paying, whichever first. Null when no active Unpaid ticket remains (all Booked/Paid, or any Unpaid ticket already Uncompleted). paymentRequiredBy: type: - string - 'null' format: date-time description: >- Deadline by which Unpaid tickets must be paid (ISO 8601). Same value as bookingRequiredBy — an Unpaid ticket is finalized by paying OR booking, whichever first. Null when all tickets are Paid/Booked or when any Unpaid ticket has already become Uncompleted (post-20-min expiry). Derived from earliest Unpaid order createdAt + 20 min — NOT Booking.createdAt which resets on peel-off. After expiry, late payment still revives the order. tickets: type: array items: type: object properties: id: type: string description: Order / ticket identifier. example: ord_abc bookingId: type: - string - 'null' description: >- Booking this ticket belongs to. Use this as the crosswalk when the addressing unit changes after a peel-off. example: bkg_1 note: type: - string - 'null' description: Order note. status: type: - string - 'null' description: Order status. example: Processing paymentStatus: type: string description: Payment status. example: Unpaid departureDate: type: - string - 'null' format: date-time description: Departure date-time (ISO 8601). source: type: - string - 'null' description: Route source. example: PrexSell refundAmount: description: >- Refund amount after cancellation (populated by updateOrderStatus). ADR-0033 §3 — cancel response carries the just-persisted value. example: 800 passenger: type: - object - 'null' properties: id: type: string description: Passenger identifier. example: pass_1 firstName: type: string description: First name. example: Іван lastName: type: string description: Last name. example: Петренко email: type: - string - 'null' description: Contact email. example: ivan@example.com phones: type: array items: type: object properties: id: type: string description: Phone record identifier. example: ph_1 phone: type: string description: Phone number. example: '+380501234567' messengers: type: array items: type: string description: Messenger apps tied to this number. example: - Viber required: - id - phone description: Passenger phone. description: >- Contact phones (createdAt/companyId/passengerId stripped by mapTicketsKeysForRestRes). required: - id description: Passenger details. price: type: - object - 'null' properties: id: type: string amount: description: Ticket price amount. example: 1200 currency: type: string enum: - CZK - UAH - EUR - USD - PLN description: >- Currency code (ADR-0033 §3 — single source: CURRENCIES). example: UAH required: - id - currency description: Ticket price. discount: type: - object - 'null' properties: id: type: string name: type: string rule: type: string enum: - Amount - Percent - Overwrite amount: description: Discount amount. example: 200 startDate: type: - string - 'null' format: date-time description: Discount validity start (ISO 8601). endDate: type: - string - 'null' format: date-time description: Discount validity end (ISO 8601). required: - id - name - rule description: Applied discount. slices: type: array items: type: object properties: id: type: string description: Slice identifier. example: sl_abc duration: type: number description: Journey duration in minutes. example: 480 arrivalDate: type: - string - 'null' format: date-time description: Arrival date-time (ISO 8601). departureDate: type: - string - 'null' format: date-time description: Departure date-time (ISO 8601). seat: type: - object - 'null' properties: id: type: string description: Seat identifier. example: seat_1 label: type: string description: Seat label. example: 12A required: - id - label description: >- Assigned seat for this slice (ADR-0033 §3 — 'seat made honest'). Populated from order.busSeat; null when no seat assignment. bus: type: - object - 'null' properties: id: type: string seatsQty: type: integer registrationNumber: type: string brand: type: string model: type: string images: type: array items: type: object properties: id: type: string description: Image identifier. example: img_abc url: type: string description: Image URL (CDN-rewritten). example: https://example.com/bus.jpg name: type: string description: Image label. example: Bus exterior required: - id - url description: A bus image. description: >- Bus images (URL-rewritten by CDN helper). required: - id - seatsQty - registrationNumber - brand - model description: Bus assigned to the journey slice. carriage: type: - object - 'null' properties: id: type: string name: type: string phones: type: array items: type: string example: '+380501234567' description: Carriage contact phones (+ prefixed). required: - id - name description: Carriage assigned to the journey slice. route: type: - object - 'null' properties: id: type: string name: type: string slug: type: - string - 'null' description: type: - string - 'null' company: type: - object - 'null' properties: id: type: string name: type: - string - 'null' slug: type: string description: Company URL slug. example: test-carrier ceo: type: - string - 'null' description: CEO name. example: Jane Doe partnerCompany: type: - string - 'null' description: Partner company name. logoUrl: type: - string - 'null' description: Company logo URL. example: https://example.com/logo.png email: type: string description: Contact email. example: ops@carrier.com website: type: - string - 'null' description: Company website URL. example: https://carrier.com rules: type: - string - 'null' description: Carrier rules text. socials: type: array items: type: string description: Company social media links. example: - https://fb.me/carrier required: - id - name description: >- Carrier company (secret fields stripped by mapTicketsKeysForRestRes). permissions: type: array items: type: object properties: id: type: string description: Permission identifier. example: perm_1 role: type: string description: Role this permission applies to. example: Agent accesses: type: array items: type: string description: Access names granted. example: - book type: type: string description: Permission type. example: Partner required: - id - role - accesses - type description: >- Route permission (filtered to type=Partner AND role=Agent for partners). description: >- Route permissions filtered to type=Partner AND role=Agent. services: type: array items: type: object properties: id: type: string description: Service identifier. example: svc_1 name: type: string description: Service name. example: Wi-Fi required: - id - name description: >- An amenity or service offered on this route. description: Services available on this route. required: - id - name - slug - description description: Route for this journey slice. stops: type: array items: type: object properties: id: type: string arrivalTime: type: - string - 'null' description: Arrival time at this stop (HH:MM). departureTime: type: - string - 'null' description: Departure time from this stop (HH:MM). platform: type: - string - 'null' description: Platform number or label. arrivalDate: type: - string - 'null' format: date-time description: >- Arrival date-time at this stop (ISO 8601). place: type: - string - 'null' description: Stop place / station name. latitude: type: - number - 'null' description: Latitude coordinate. example: 50.45 longitude: type: - number - 'null' description: Longitude coordinate. example: 30.52 city: type: - object - 'null' properties: id: type: string name: type: string slug: type: string country: type: string enum: - UA - TR - PL - CZ - IT - DE - SK - HU - BE - NL - RO - BG - FR - AT - LT - LV - EE - ES - LU - CH - GR - MD - SI timeZone: type: - string - 'null' required: - id - name - slug - country - timeZone description: City at this stop. required: - id description: A stop on the journey slice. description: Ordered stops for this slice. required: - id description: One leg of a multi-slice journey. description: Journey slices for this ticket. required: - id - slices description: A single ticket (order) within a booking. description: >- Partner-filtered tickets. A ticket is included when it belongs to this booking AND was created by this partner. Sibling tickets from other partners in the same booking are not visible. required: - id - createdAt - updatedAt - departureDate - onboardingDateTime - status - bookingRequiredBy - paymentRequiredBy - tickets additionalProperties: false description: >- A booking aggregate. One booking = N tickets (orders). Addresses the same row the beta passenger surface (myBookings/currentBooking) uses. Note: Booking.departureDate is the UTC onboarding instant (ADR-0008) — different from ticket-level departureDate which is a local date. example: id: bkg_1 createdAt: '2026-06-14T00:05:00.000Z' updatedAt: '2026-06-14T00:05:00.000Z' departureDate: '2026-06-15T03:30:00.000Z' onboardingDateTime: '2026-06-15T03:30:00.000Z' status: Upcoming bookingRequiredBy: '2026-06-14T00:25:00.000Z' paymentRequiredBy: '2026-06-14T00:25:00.000Z' tickets: - id: ord_abc bookingId: bkg_1 note: null status: Processing paymentStatus: Unpaid departureDate: '2026-06-15T00:00:00.000Z' source: PrexSell refundAmount: null passenger: id: pass_1 firstName: Іван lastName: Петренко email: ivan@example.com phones: - id: ph_1 phone: '+380501234567' messengers: - Viber price: id: price-1 amount: 1450 currency: UAH discount: id: disc-1 name: Студентська знижка rule: Percent amount: 100 startDate: '2026-06-01T00:00:00.000Z' endDate: '2026-12-31T23:59:59.000Z' slices: - id: sl_abc duration: 480 departureDate: '2026-06-15T00:00:00.000Z' arrivalDate: '2026-06-15T08:00:00.000Z' seat: id: seat_1 label: 12A bus: id: bus-1 seatsQty: 50 registrationNumber: AA1234BB brand: Mercedes-Benz model: Tourismo images: - id: img-1 url: https://example.com/bus.jpg name: Bus exterior carriage: id: carriage-1 name: Автопарк №1 phones: - '+380501234567' route: id: route-1 name: Київ — Варшава slug: kyiv-warsaw description: Щоденний нічний рейс company: id: company-1 name: PrexSell Lines slug: prexsell-lines ceo: Олена Коваль partnerCompany: null logoUrl: https://example.com/logo.png email: ops@prexsell-lines.com website: https://prexsell-lines.com rules: >- Пасажир має прибути за 20 хвилин до відправлення. socials: - https://facebook.com/prexsell.lines permissions: - id: perm-1 role: Agent accesses: - book - cancel type: Partner services: - id: svc-1 name: Wi-Fi - id: svc-2 name: Кондиціонер stops: - id: stop-1 departureTime: '06:30' arrivalTime: null platform: '3' arrivalDate: null place: Центральний автовокзал latitude: 50.4501 longitude: 30.5234 city: id: city-kyiv name: Київ slug: kyiv country: UA timeZone: Europe/Kyiv - id: stop-2 departureTime: null arrivalTime: '08:00' platform: '5' arrivalDate: '2026-06-15T08:00:00.000Z' place: Dworzec Zachodni latitude: 52.2297 longitude: 21.0122 city: id: city-warsaw name: Варшава slug: warsaw country: PL timeZone: Europe/Warsaw required: - booking description: Create booking result. required: - data example: data: booking: id: bkg_1 createdAt: '2026-06-14T00:05:00.000Z' updatedAt: '2026-06-14T00:05:00.000Z' departureDate: '2026-06-15T03:30:00.000Z' onboardingDateTime: '2026-06-15T03:30:00.000Z' status: Upcoming bookingRequiredBy: '2026-06-14T00:25:00.000Z' paymentRequiredBy: '2026-06-14T00:25:00.000Z' tickets: - id: ord_abc bookingId: bkg_1 note: null status: Processing paymentStatus: Unpaid departureDate: '2026-06-15T00:00:00.000Z' source: PrexSell refundAmount: null passenger: id: pass_1 firstName: Іван lastName: Петренко email: ivan@example.com phones: - id: ph_1 phone: '+380501234567' messengers: - Viber price: id: price-1 amount: 1450 currency: UAH discount: id: disc-1 name: Студентська знижка rule: Percent amount: 100 startDate: '2026-06-01T00:00:00.000Z' endDate: '2026-12-31T23:59:59.000Z' slices: - id: sl_abc duration: 480 departureDate: '2026-06-15T00:00:00.000Z' arrivalDate: '2026-06-15T08:00:00.000Z' seat: id: seat_1 label: 12A bus: id: bus-1 seatsQty: 50 registrationNumber: AA1234BB brand: Mercedes-Benz model: Tourismo images: - id: img-1 url: https://example.com/bus.jpg name: Bus exterior carriage: id: carriage-1 name: Автопарк №1 phones: - '+380501234567' route: id: route-1 name: Київ — Варшава slug: kyiv-warsaw description: Щоденний нічний рейс company: id: company-1 name: PrexSell Lines slug: prexsell-lines ceo: Олена Коваль partnerCompany: null logoUrl: https://example.com/logo.png email: ops@prexsell-lines.com website: https://prexsell-lines.com rules: >- Пасажир має прибути за 20 хвилин до відправлення. socials: - https://facebook.com/prexsell.lines permissions: - id: perm-1 role: Agent accesses: - book - cancel type: Partner services: - id: svc-1 name: Wi-Fi - id: svc-2 name: Кондиціонер stops: - id: stop-1 departureTime: '06:30' arrivalTime: null platform: '3' arrivalDate: null place: Центральний автовокзал latitude: 50.4501 longitude: 30.5234 city: id: city-kyiv name: Київ slug: kyiv country: UA timeZone: Europe/Kyiv - id: stop-2 departureTime: null arrivalTime: '08:00' platform: '5' arrivalDate: '2026-06-15T08:00:00.000Z' place: Dworzec Zachodni latitude: 52.2297 longitude: 21.0122 city: id: city-warsaw name: Варшава slug: warsaw country: PL timeZone: Europe/Warsaw '400': description: Standard error response body. content: application/json: schema: type: object properties: errors: type: array items: type: object additionalProperties: {} description: >- Array of error objects. Shape depends on origin: CustomError paths emit { message, errorCode } items; request-validation paths emit { message, field, ...constraint params } items, where `field` is the offending request field (e.g. "departureDate"). example: - message: Offer expired errorCode: OFFER_EXPIRED required: - errors example: errors: - message: Offer expired errorCode: OFFER_EXPIRED '401': description: Standard error response body. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: AUTH_INVALID_CREDENTIALS errorCode: type: string example: UNAUTHORIZED details: {} required: - message required: - errors example: errors: - message: AUTH_INVALID_CREDENTIALS errorCode: UNAUTHORIZED security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Partner API key, sent in the `x-api-key` request header. Required for bookable offer search and all booking operations. To obtain a key, register as a PREXSELL partner in the backoffice (backoffice.prexsell.com, or staging.backoffice.prexsell.com for staging) and contact support if you need help. ````