Create a booking order
POST/v2/booking-orders
Requires your API key in the X-API-Key header.
Creates a new order together with its first lines — v2 bookings, retail lines, or
both — in a single atomic call. At least one line is required (400, ORDER_EMPTY).
Each booking is created in ON_HOLD status with a 15-minute hold timer; if the
order isn't confirmed before the timer runs out, the booking expires and the order
becomes EXPIRED.
Each booking needs a variantId + availabilitySlotId pair and participantCounts
(participant-type ID to head count). Pricing is always computed server-side from the
variant/option configuration — don't send prices. durationUnits is required for
DURATION_BASED pricing options and rejected otherwise. A too-large party or an
unavailable slot returns 400; booking a slot in the past, or inside the
experience's cut-off window, also returns 400.
Retail lines (retailItems) buy SKUs of retail products or gift vouchers. They hold
their units for as long as the order is held and are sold at confirm; a counted SKU
without enough free units returns 400 (RETAIL_STOCK_INSUFFICIENT). To redeem a gift
voucher, send its code as voucherCode: every booking is checked against the voucher
(rules under POST .../confirm) and holds one of its uses, but keeps its real price
until confirm.
Returns 201 with the full order and its bookings. No confirmation side effects
(emails, PMS, notifications) fire here — those are dispatched by POST .../confirm.
curl -X POST "https://api.turneo.co/v2/booking-orders" \
-H "X-API-Key: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"travelerInformation": {
"email": "guest@example.com"
},
"bookings": [
{
"variantId": "3f2e6d1c-8a4b-4f0e-9c7d-2b1a0e9f8d7c",
"availabilitySlotId": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"participantCounts": {
"c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d": 2
}
}
]
}'Request bodyapplication/json, required
travelerInformationobjectShared traveler info, copied to bookings that don't provide their own.
Child fields
emailstring (email)Traveler's email address — used for confirmation, ticket and payment-link emails.
- Example:
guest@example.com
firstNamestringnullableTraveler's first name.
- Example:
Alice
lastNamestringnullableTraveler's last name.
- Example:
Smith
phonestringnullableTraveler's phone number in international format.
- Example:
+385911234567
bookingsobject[]Bookings to create. Required unless
retailItemsis sent.Child fields
variantIdstring (uuid)requiredUUID of the variant to book. Must be active and belong to an active option/experience.
- Example:
3f2e6d1c-8a4b-4f0e-9c7d-2b1a0e9f8d7c
availabilitySlotIdstring (uuid)requiredUUID of the availability slot to book. Must belong to the same option as the variant and be active and bookable.
- Example:
9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
participantCountsmap of integerrequiredMap of participant-type UUID to positive head count. Types must belong to the experience and not be disabled on the option; capacity-exempt types (e.g. infants) do not count against the variant's participant limit.
bookingAddonsobject[]Add-ons to book. For QUANTITY_SELECTOR add-ons the quantity is capped by the add-on's maxQuantity; for CHECKBOX add-ons the server derives the effective quantity from the participant count.
Child fields
addonIdstring (uuid)requiredUUID of an active add-on on the option.
- Example:
5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d
quantityintegerrequiredRequested quantity.
- Limits:
- minimum 1
- Example:
2
extraFieldResponsesobject[]Answers to the option's extra fields. Can also be provided later via PATCH; required fields are enforced at confirm time, not here.
Child fields
fieldIdstring (uuid)requiredUUID of an active extra field on the option.
- Example:
aa1bb2cc-3dd4-4ee5-9ff6-0a1b2c3d4e5f
responsestringrequiredThe traveler's answer. For checkbox fields use "true"/"false".
- Example:
Vegetarian
durationUnitsintegerNumber of duration-increment blocks to book. Required for DURATION_BASED pricing options and rejected for all other pricing models.
- Limits:
- minimum 1
- Example:
2
travelerInformationobjectBooking-level traveler info. Defaults to the order-level value when omitted.
Child fields
emailstring (email)Traveler's email address — used for confirmation, ticket and payment-link emails.
- Example:
guest@example.com
firstNamestringnullableTraveler's first name.
- Example:
Alice
lastNamestringnullableTraveler's last name.
- Example:
Smith
phonestringnullableTraveler's phone number in international format.
- Example:
+385911234567
resellerobjectStore/agent attribution (storeId, storeName, agentName...) merged into the booking metadata.
resellerReferencestringReseller's internal reference for this booking.
- Limits:
- up to 128 characters
- Example:
HOTEL-4711
paymentobjectnullableInitial payment details. When omitted, reseller-flow callers default to RESELLER_CONCIERGE / PAYMENT_COLLECTED; everyone else to null / PAYMENT_PENDING.
Child fields
codestringnullablePayment reference — e.g. a Stripe payment-intent id, sent by the client at confirm time.
- Example:
pi_3OqX8s2eZvKYlo2C
statusstringPayment status.
- Allowed values:
PAYMENT_PENDINGPAYMENT_COLLECTEDREFUNDEDFREE- Example:
PAYMENT_COLLECTED
processedBystringnullableWho collects the money. TURNEO (Stripe via Turneo — the only type eligible for auto-capture), TURNEO_LINK (payment link), RESELLER_CONCIERGE / RESELLER_ROOM / RESELLER_CARD (reseller collects), PMS_ROOM_CHARGE, ORGANIZER, or RETAIL_VOUCHER (paid with a gift voucher; to redeem one, send it in the order-level
paymentat confirm, with the voucher code ascode).- Example:
TURNEO
viaPaymentLinkbooleanPresent and true when the payment was initiated through a payment link.
- Example:
false
meetingPointIdstring (uuid)UUID of one of the experience's predefined meeting points.
- Example:
6e5f4a3b-2c1d-4e0f-9a8b-7c6d5e4f3a2b
meetingPointobjectCustom pickup location, used when meetingPointId is not supplied.
notesobjectBooking notes keyed by author (
fromSeller,fromOrganizer).bookingSourcestringSource identifier of the sales channel.
- Limits:
- up to 36 characters
- Example:
hub
emailNotificationstring (email)[]Extra email addresses to notify about this booking.
metadataobjectArbitrary JSON metadata stored on the booking.
languagestringLanguage code for traveler-facing communication. Defaults to the request language.
- Limits:
- up to 5 characters
- Example:
en
skipCutoffbooleanReserved for Turneo's concierge tooling — silently ignored for API-key integrations.
- Default:
false- Example:
false
resourcesstring (uuid)[]Specific resources to book (a therapist, room, sunbed, table or rental unit), by id from the option's
resourceGroups. Each must belong to one of the option's resource groups and be free for the slot, or the request returns 400. Omit it and Turneo assigns resources automatically.
retailItemsobject[]Retail and gift voucher lines to buy. Required unless
bookingsis sent.Child fields
retailSkuIdstring (uuid)requiredUUID of the SKU to buy (from
retailSkuson the product detail). It must be enabled, priced and on anACTIVEproduct, otherwise 400 (RETAIL_SKU_UNAVAILABLEorRETAIL_EXPERIENCE_UNAVAILABLE); a counted SKU without enough free units returns 400 (RETAIL_STOCK_INSUFFICIENT).- Example:
8f14e45f-ceea-4e5b-b0d4-9f3c1a2b3c4d
quantityintegerrequiredUnits to buy. Price is the SKU's unit price times this. A gift voucher line must be exactly 1 (400,
VOUCHER_PURCHASE_SINGLE_ITEM_REQUIRED); buy several vouchers as several lines.- Limits:
- minimum 1
- Example:
2
extraFieldResponsesobjectnullableAnswers to the SKU's questions, keyed by question UUID. They can also be sent later with
PATCH /v2/booking-orders/{id}; required ones are enforced at confirm.recipientEmailstring (email)nullableGift voucher lines only. The voucher code is emailed here instead of to the buyer. Sending it on any other line returns 400 (
RETAIL_RECIPIENT_FIELDS_UNSUPPORTED).- Example:
recipient@guest.example
recipientNamestringnullableGift voucher lines only. Name of the gift recipient.
- Limits:
- up to 255 characters
- Example:
Alex Example
voucherCodestringnullableA gift voucher code to pay for this order's bookings with. Each booking is checked against the voucher on creation (400 on
retail_voucher_code, e.g.VOUCHER_INVALID,VOUCHER_USES_EXHAUSTED,VOUCHER_EXPERIENCE_OUT_OF_SCOPE) and holds one of its uses; prices drop to 0 at confirm. Remove it withPOST /v2/booking-orders/{id}/remove-voucher. Not for promo codes.- Limits:
- up to 24 characters
- Example:
7WF4MRY2KC8N
emailNotificationstring (email)[]Email addresses to notify about the order.
resellerReferencestringReseller's internal order reference.
- Limits:
- up to 128 characters
- Example:
HOTEL-4711
bookingSourcestringSource identifier of the sales channel.
- Limits:
- up to 36 characters
- Example:
hub
utmMediumstringUTM medium tracking parameter.
- Limits:
- up to 128 characters
- Example:
email
utmSourcestringUTM source tracking parameter.
- Limits:
- up to 128 characters
- Example:
newsletter
Example: Single booking, minimal payload
{
"travelerInformation": {
"email": "guest@example.com"
},
"bookings": [
{
"variantId": "3f2e6d1c-8a4b-4f0e-9c7d-2b1a0e9f8d7c",
"availabilitySlotId": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"participantCounts": {
"c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d": 2
}
}
]
}Example: Reseller concierge booking with a reference
{
"travelerInformation": {
"email": "guest@example.com",
"firstName": "Alice",
"lastName": "Smith"
},
"resellerReference": "HOTEL-4711",
"bookings": [
{
"variantId": "3f2e6d1c-8a4b-4f0e-9c7d-2b1a0e9f8d7c",
"availabilitySlotId": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"participantCounts": {
"c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d": 1
}
}
]
}Example: Buy a retail product and a gift voucher
{
"travelerInformation": {
"email": "guest@example.com"
},
"retailItems": [
{
"retailSkuId": "8f14e45f-ceea-4e5b-b0d4-9f3c1a2b3c4d",
"quantity": 2
},
{
"retailSkuId": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
"quantity": 1,
"recipientEmail": "recipient@guest.example",
"recipientName": "Alex Example"
}
]
}Example: Book an experience with a gift voucher
{
"travelerInformation": {
"email": "guest@example.com"
},
"voucherCode": "7WF4MRY2KC8N",
"bookings": [
{
"variantId": "3f2e6d1c-8a4b-4f0e-9c7d-2b1a0e9f8d7c",
"availabilitySlotId": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"participantCounts": {
"c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d": 1
}
}
]
}Responses
201object
Order created with all lines ON_HOLD.
idstring (uuid)Order UUID.
- Example:
0f47ac10-b58c-4372-a567-0e02b2c3d479
statusstringDerived order status, counting bookings and retail lines alike. ON_HOLD — all active lines are still on hold; BOOKED — at least one line progressed past ON_HOLD; EXPIRED — the order has lines but none are active.
- Allowed values:
ON_HOLDBOOKEDEXPIRED- Example:
ON_HOLD
travelerInformationobjectnullableTraveler contact information shared by the bookings in the order. Individual bookings may carry their own traveler information which takes precedence.
Child fields
emailstring (email)Traveler's email address — used for confirmation, ticket and payment-link emails.
- Example:
guest@example.com
firstNamestringnullableTraveler's first name.
- Example:
Alice
lastNamestringnullableTraveler's last name.
- Example:
Smith
phonestringnullableTraveler's phone number in international format.
- Example:
+385911234567
bookingsobject[]The order's bookings, newest first. EXPIRED and REMOVED bookings are excluded — unless every non-removed booking has expired, in which case the EXPIRED bookings are returned so the dead cart can be rendered.
Child fields
idstring (uuid)Booking UUID.
- Example:
7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a
bookingCodestringShort human-readable booking code used on tickets and folios.
- Example:
TRN-8F3K2A
bookingStatusstringBooking lifecycle status. ON_HOLD (reserved, 15-minute hold), PENDING (confirmed, awaiting organizer acceptance), ACCEPTED (live), COMPLETED, CANCELLED, EXPIRED (hold or organizer-response timer ran out), NO_SHOW, REJECTED, REMOVED (taken out of the cart).
- Allowed values:
ON_HOLDPENDINGACCEPTEDCOMPLETEDCANCELLEDEXPIREDNO_SHOWREJECTEDREMOVED- Example:
ON_HOLD
experienceobjectnullableFull embedded experience object (id, name, images, location, duration, refund policy, organizer...). Shape matches the v2 experience read schema.
optionobjectnullableFull embedded option object including its variants (with pricing tiers and participant prices), add-ons and extra fields. Shape matches the v2 option read schema.
variantIdstring (uuid)UUID of the booked variant — references into the embedded option's variants.
- Example:
3f2e6d1c-8a4b-4f0e-9c7d-2b1a0e9f8d7c
availabilitySlotIdstring (uuid)UUID of the booked availability slot.
- Example:
9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
orderIdstring (uuid)UUID of the parent order.
- Example:
0f47ac10-b58c-4372-a567-0e02b2c3d479
redeemedRetailItemIdstring (uuid)nullableThe gift voucher's retail item this booking is redeemed with, or null.
- Example:
6c7d8e9f-0a1b-4c2d-8e3f-4a5b6c7d8e9f
slotStartTimeobjectnullableA local date/time pair in the experience's timezone.
Child fields
datestring (date)nullableLocal date (YYYY-MM-DD).
- Example:
2026-07-10
timestringnullableLocal time of day (HH:MM:SS). Null for date-only (all-day) slots.
- Example:
10:00:00
slotEndTimeobjectnullableBooking occupancy end in local time — derived from the resolved resource-block window when present, otherwise start + bookedDuration. Null for all-day date-only slots.
Child fields
datestring (date)nullableLocal date (YYYY-MM-DD).
- Example:
2026-07-10
timestringnullableLocal time of day (HH:MM:SS). Null for date-only (all-day) slots.
- Example:
10:00:00
timestring (date-time)nullableBooking start as a UTC timestamp.
- Example:
2026-07-10T08:00:00Z
participantCountsmap of integerMap of participant-type UUID to booked head count.
totalParticipantsintegerTotal booked participants across all participant types.
- Example:
2
bookedDurationobjectBooked duration as
{days, hours, minutes}, computed from the option configuration.durationUnitsintegernullableNumber of duration-increment blocks booked. Only set for DURATION_BASED pricing.
- Example:
2
retailPriceBreakdownobject[]Line-by-line retail price breakdown (one entry per participant type, add-on and discount) with label, quantity and price.
bookingAddonsobject[]Booked add-ons with resolved names and effective quantities.
Child fields
addonIdstring (uuid)Add-on UUID.
- Example:
5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d
addonNamestringAdd-on name in the request language.
- Example:
Hotel transfer
quantityintegerEffective booked quantity (server-derived for per-person checkbox add-ons).
- Example:
2
pricestringnullableUnit price of the add-on as a decimal string.
- Example:
15.00
perPersonbooleanWhether the add-on is priced per person.
- Example:
true
extraFieldResponsesmap of stringnullableMap of extra-field UUID to the traveler's answer.
storeExtraFieldResponsesobjectnullableAnswers to the store's checkout questions, keyed by question id; each value is a string, a boolean (checkbox) or null. The questions themselves are defined on the store config (
checkout.questions), not on the option, and are answered once per order — every booking of an order carries the same map. Returned only to the booking's reseller; null for everyone else, organizer-side callers included.alternativeSlotsobject[]nullableAlternative slots offered by the organizer on a PENDING booking, or null when none were offered.
Child fields
idstring (uuid)Alternative slot UUID.
- Example:
2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e
startDatestring (date)nullableLocal start date of the alternative slot.
- Example:
2026-07-11
startTimestringnullableLocal start time of the alternative slot.
- Example:
14:00:00
resellerobjectEmbedded reseller partner (id, name, logo...) enriched with attribution from the booking metadata — storeId, storeName, storeSubdomain, agentName, agentReference, hotelName, roomNumber — when present.
finalPriceobjectTotal retail price the traveler pays for this booking.
Child fields
amountnumberAmount in major currency units.
- Example:
250
currencystringISO 4217 currency code.
- Example:
EUR
basePriceobjectBase (pre-commission) price of the booking.
Child fields
amountnumberAmount in major currency units.
- Example:
250
currencystringISO 4217 currency code.
- Example:
EUR
netRateobjectOrganizer's payout amount for this booking.
Child fields
amountnumberAmount in major currency units.
- Example:
250
currencystringISO 4217 currency code.
- Example:
EUR
discountobjectnullableAutomatic slot/option discount applied at booking time, or null.
voucherobjectnullableApplied voucher details (code, discount), or null when no voucher is applied.
conciergeDiscountobjectnullableManually applied concierge discount (amount, note), or null.
paymentobjectnullablePayment details for one booking.
Child fields
codestringnullablePayment reference — e.g. a Stripe payment-intent id, sent by the client at confirm time.
- Example:
pi_3OqX8s2eZvKYlo2C
statusstringPayment status.
- Allowed values:
PAYMENT_PENDINGPAYMENT_COLLECTEDREFUNDEDFREE- Example:
PAYMENT_COLLECTED
processedBystringnullableWho collects the money. TURNEO (Stripe via Turneo — the only type eligible for auto-capture), TURNEO_LINK (payment link), RESELLER_CONCIERGE / RESELLER_ROOM / RESELLER_CARD (reseller collects), PMS_ROOM_CHARGE, ORGANIZER, or RETAIL_VOUCHER (paid with a gift voucher; to redeem one, send it in the order-level
paymentat confirm, with the voucher code ascode).- Example:
TURNEO
viaPaymentLinkbooleanPresent and true when the payment was initiated through a payment link.
- Example:
false
travelerInformationobjectnullableBooking-level traveler info. Inherited from the order at confirm time when not set.
Child fields
emailstring (email)Traveler's email address — used for confirmation, ticket and payment-link emails.
- Example:
guest@example.com
firstNamestringnullableTraveler's first name.
- Example:
Alice
lastNamestringnullableTraveler's last name.
- Example:
Smith
phonestringnullableTraveler's phone number in international format.
- Example:
+385911234567
meetingPointobjectnullableResolved meeting point / pickup details for the booking.
resellerReferencestringnullableReseller's internal reference for this booking.
- Example:
HOTEL-4711
resellerPropertyobjectnullableThe reseller property (hotel) the booking is attributed to — id, name, location, partner, parentProperty, roomCount and a pmsIntegration summary — or null.
pmsBookingIdstringnullableExternal PMS reservation id linked to this booking (e.g. Valamar master id).
- Example:
123456789
bookingSourcestringnullableSource identifier of the sales channel that created the booking.
- Example:
hub
emailNotificationstring (email)[]nullableExtra email addresses notified about this booking.
metadataobjectnullableArbitrary attribution metadata (store/agent details, external provider ids).
languagestringLanguage code used for traveler-facing communication.
- Example:
en
cancellationobjectnullableCancellation details (cancelledBy, cancelledAt, cancellationFeeAmount), or null.
reviewobjectnullableThe booking's review (rating, reviewText, status...), or null when not reviewed.
resourcesobject[]Resources (guides, vehicles) assigned to the booking, deduplicated.
Child fields
idstring (uuid)Resource UUID.
- Example:
8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f
namestringResource display name.
- Example:
Kayak guide Ivan
notesobjectnullableBooking notes keyed by author — fromSeller, fromOrganizer, fromTraveler. Null when empty.
createdAtstring (date-time)When the booking was created.
- Example:
2026-07-02T09:15:00Z
updatedAtstring (date-time)When the booking was last modified.
- Example:
2026-07-02T09:20:00Z
retailItemsobject[]The order's retail and gift voucher lines, newest first, selected like
bookings: EXPIRED and REMOVED lines are excluded unless the whole order has expired.voucherCodeis always null here; the gift voucher code is emailed to its holder.Child fields
idstring (uuid)Line UUID.
- Example:
7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a
orderIdstring (uuid)UUID of the order the line belongs to.
- Example:
0f47ac10-b58c-4372-a567-0e02b2c3d479
retailCodestringShort reference for the line (10 characters). Usable in place of the UUID in
/v2/retail-items/{id}and as a filter. It is not a gift voucher code.- Example:
3HCX9KPT2L
retailSkuIdstring (uuid)UUID of the purchased SKU.
- Example:
8f14e45f-ceea-4e5b-b0d4-9f3c1a2b3c4d
skuCodestringnullableThe purchased SKU's stock-keeping code.
- Example:
TSHIRT-RED-M
experienceIdstring (uuid)UUID of the retail product.
- Example:
0d4dbb2e-8a51-4a4b-9d3e-6f2b7c1a9e55
experienceobjectThe retail product, in the experience read shape without the fields that only bookable experiences have (options, participant types, meeting points, booking type).
quantityintegerUnits bought. Always 1 on a gift voucher line.
- Example:
2
imageUrlstring (uri)nullableThe SKU's image, or the product's first image when the SKU has none.
- Example:
https://images.example.com/tshirt-red.jpg
variantLabelsstring[]Labels of the purchased SKU's variation values, in axis order, in the line's language. Empty for a product without variations.
finalPriceobjectWhat the buyer pays for the line (unit price times quantity, minus any concierge discount).
Child fields
amountnumberAmount in major currency units.
- Example:
250
currencystringISO 4217 currency code.
- Example:
EUR
netRateobjectWhat the product's organizer receives for the line (line total minus commission).
Child fields
amountnumberAmount in major currency units.
- Example:
250
currencystringISO 4217 currency code.
- Example:
EUR
statusstringON_HOLDwhile the order is unconfirmed;PAIDonce it is confirmed;DELIVEREDafter you mark it delivered;CANCELLEDafter a cancellation.EXPIREDmeans the order's hold ran out,REMOVEDthat the line was taken out of the order.- Allowed values:
ON_HOLDPAIDDELIVEREDCANCELLEDEXPIREDREMOVED- Example:
PAID
paidAtstring (date-time)nullableWhen the order was confirmed. Retail has no service date, so reporting uses this.
- Example:
2026-07-15T09:12:00Z
paymentobjectnullablePayment details for one booking.
Child fields
codestringnullablePayment reference — e.g. a Stripe payment-intent id, sent by the client at confirm time.
- Example:
pi_3OqX8s2eZvKYlo2C
statusstringPayment status.
- Allowed values:
PAYMENT_PENDINGPAYMENT_COLLECTEDREFUNDEDFREE- Example:
PAYMENT_COLLECTED
processedBystringnullableWho collects the money. TURNEO (Stripe via Turneo — the only type eligible for auto-capture), TURNEO_LINK (payment link), RESELLER_CONCIERGE / RESELLER_ROOM / RESELLER_CARD (reseller collects), PMS_ROOM_CHARGE, ORGANIZER, or RETAIL_VOUCHER (paid with a gift voucher; to redeem one, send it in the order-level
paymentat confirm, with the voucher code ascode).- Example:
TURNEO
viaPaymentLinkbooleanPresent and true when the payment was initiated through a payment link.
- Example:
false
cancellationobjectnullableCancellation details (
cancelledBy,cancelledAtin UTC,cancelledReason,cancellationFeeAmount,cancellationFeeCurrency). Null unless the line isCANCELLED.Child fields
cancelledBystringWho cancelled the booking.
- Allowed values:
TravelerOrganizerResellerAdmin- Example:
Traveler
cancelledAtstringWhen the cancellation happened, as a naive local timestamp in the experience's timezone.
- Example:
2026-07-10T14:30:00
cancelledReasonstringnullableFree-text reason supplied by the canceller.
- Example:
Change of plans
cancellationFeeAmountnumberFee retained from the traveler. 0 means a full refund; the full price means non-refundable.
- Example:
25
cancellationFeeCurrencystringCurrency of the cancellation fee (the booking's currency).
- Example:
EUR
refundPercentagenumberThe refund-policy tier percentage that was applied. Absent when the fee was forced to 0 (organizer cancel, or traveler cancel after alternatives were offered).
- Example:
75
resellerobjectnullableThe selling partner, enriched with the store and agent attribution captured at checkout.
resellerPropertyobjectnullableThe property (hotel) the sale is attributed to, or null.
languagestringnullableLanguage of the buyer's checkout, used for emails and labels.
- Example:
en
travelerInformationobjectnullableThe buyer's details, from the order. Retail lines have no traveler of their own.
Child fields
emailstring (email)Traveler's email address — used for confirmation, ticket and payment-link emails.
- Example:
guest@example.com
firstNamestringnullableTraveler's first name.
- Example:
Alice
lastNamestringnullableTraveler's last name.
- Example:
Smith
phonestringnullableTraveler's phone number in international format.
- Example:
+385911234567
conciergeDiscountobjectnullableDiscount applied to the line at checkout, as
{amount, currency, note}, or null.allowedUsesintegernullableTotal uses a gift voucher line grants. Null on other lines.
- Example:
5
remainingUsesintegernullableUses a gift voucher line has left; 0 unless the line is
PAID. Null on other lines.- Example:
3
voucherCodestringnullableThe gift voucher code. Returned only by the
/v2/retail-itemsendpoints, so the buyer of a gift never sees it on the order; the holder receives it by email. Null on other lines.- Example:
7WF4MRY2KC8N
recipientEmailstring (email)nullableGift recipient of a voucher. The voucher email goes here instead of to the buyer.
- Example:
recipient@guest.example
recipientNamestringnullableName of the gift recipient.
- Example:
Alex Example
extraFieldResponsesobjectnullableThe buyer's answers to the SKU's questions, keyed by question UUID.
createdAtstring (date-time)When the line was added to the order.
- Example:
2026-07-15T09:05:00Z
finalPriceobjectSum of the final prices of the displayed bookings and retail lines, excluding refunded ones. Currency comes from the first booking (or retail line); defaults to the platform currency with amount 0 for an empty order.
Child fields
amountnumberAmount in major currency units.
- Example:
250
currencystringISO 4217 currency code.
- Example:
EUR
basePricenumberSum of the base (net-rate) prices of the displayed bookings and retail lines, rounded to 2 decimals.
- Example:
200
resellerReferencestringnullableReseller's internal order reference.
- Example:
HOTEL-4711
emailNotificationstring (email)[]nullableEmail addresses to notify about the order; inherited by bookings without their own list.
bookingSourcestringnullableSource identifier of the sales channel (e.g. store subdomain, "hub").
- Example:
hub
utmMediumstringnullableUTM medium tracking parameter captured at checkout.
- Example:
email
utmSourcestringnullableUTM source tracking parameter captured at checkout.
- Example:
newsletter
storeobjectStore attribution derived from the first booking's metadata. All fields are null when the order was not placed through a store.
Child fields
idstringnullableStore identifier (MongoDB id) the order was placed through.
- Example:
64f1a2b3c4d5e6f7a8b9c0d1
subdomainstringnullableStore subdomain.
- Example:
hotel-adriatic
namestringnullableStore display name.
- Example:
Hotel Adriatic Experiences
storeExtraFieldResponsesobjectnullableAnswers to the store's checkout questions, keyed by question id; each value is a string, a boolean (checkbox) or null. The questions are defined on the store config (
checkout.questions). Empty ({}) once the checkout form has been submitted with no answers — a store with no questions, or a clear — and null only for orders that never went through it: those created before this shipped, or by a client that never sends the key. Unlike the booking-level copy this is ungated — the order endpoints are already scoped to the order's creator/reseller, and checkout reads its own answers back to re-seed the form.createdAtstring (date-time)When the order was created.
- Example:
2026-07-02T09:15:00Z
updatedAtstring (date-time)When the order was last modified.
- Example:
2026-07-02T09:20:00Z
{
"id": "0f47ac10-b58c-4372-a567-0e02b2c3d479",
"status": "ON_HOLD",
"travelerInformation": {
"email": "guest@example.com",
"firstName": "Alice",
"lastName": "Smith",
"phone": "+385911234567"
},
"bookings": [
{
"id": "7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a",
"bookingCode": "TRN-8F3K2A",
"bookingStatus": "ON_HOLD",
"experience": {},
"option": {},
"variantId": "3f2e6d1c-8a4b-4f0e-9c7d-2b1a0e9f8d7c",
"availabilitySlotId": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"orderId": "0f47ac10-b58c-4372-a567-0e02b2c3d479",
"redeemedRetailItemId": "6c7d8e9f-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
"slotStartTime": {
"date": "2026-07-10",
"time": "10:00:00"
},
"slotEndTime": {
"date": "2026-07-10",
"time": "10:00:00"
},
"time": "2026-07-10T08:00:00Z",
"participantCounts": {
"c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d": 2
},
"totalParticipants": 2,
"bookedDuration": {
"days": 0,
"hours": 2,
"minutes": 0
},
"durationUnits": 2,
"retailPriceBreakdown": [
{
"label": "Adult",
"quantity": 2,
"price": 50,
"type": "PARTICIPANT"
}
],
"bookingAddons": [
{
"addonId": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
"addonName": "Hotel transfer",
"quantity": 2,
"price": "15.00",
"perPerson": true
}
],
"extraFieldResponses": {
"aa1bb2cc-3dd4-4ee5-9ff6-0a1b2c3d4e5f": "Vegetarian"
},
"storeExtraFieldResponses": {
"0d2e4f6a-8b0c-4d2e-9f1a-3b5c7d9e1f2a": "Room 204",
"7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f": true
},
"alternativeSlots": [
{
"id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"startDate": "2026-07-11",
"startTime": "14:00:00"
}
],
"reseller": {
"id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"name": "Hotel Adriatic",
"storeId": "64f1a2b3c4d5e6f7a8b9c0d1",
"storeName": "Hotel Adriatic Experiences"
},
"finalPrice": {
"amount": 250,
"currency": "EUR"
},
"basePrice": {
"amount": 250,
"currency": "EUR"
},
"netRate": {
"amount": 250,
"currency": "EUR"
},
"discount": {},
"voucher": {},
"conciergeDiscount": {},
"payment": {
"code": "pi_3OqX8s2eZvKYlo2C",
"status": "PAYMENT_COLLECTED",
"processedBy": "TURNEO",
"viaPaymentLink": false
},
"travelerInformation": {
"email": "guest@example.com",
"firstName": "Alice",
"lastName": "Smith",
"phone": "+385911234567"
},
"meetingPoint": {
"type": "CENTRAL_MEETING_POINT",
"title": "Old Town Gate",
"address": "1 Main St",
"timeBeforeStart": 15
},
"resellerReference": "HOTEL-4711",
"resellerProperty": {},
"pmsBookingId": "123456789",
"bookingSource": "hub",
"emailNotification": [
"concierge@hotel.com"
],
"metadata": {},
"language": "en",
"cancellation": {},
"review": {},
"resources": [
{
"id": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f",
"name": "Kayak guide Ivan"
}
],
"notes": {
"fromSeller": "Guest is celebrating an anniversary."
},
"createdAt": "2026-07-02T09:15:00Z",
"updatedAt": "2026-07-02T09:20:00Z"
}
],
"retailItems": [
{
"id": "7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a",
"orderId": "0f47ac10-b58c-4372-a567-0e02b2c3d479",
"retailCode": "3HCX9KPT2L",
"retailSkuId": "8f14e45f-ceea-4e5b-b0d4-9f3c1a2b3c4d",
"skuCode": "TSHIRT-RED-M",
"experienceId": "0d4dbb2e-8a51-4a4b-9d3e-6f2b7c1a9e55",
"experience": {},
"quantity": 2,
"imageUrl": "https://images.example.com/tshirt-red.jpg",
"variantLabels": [
"Red",
"M"
],
"finalPrice": {
"amount": 250,
"currency": "EUR"
},
"netRate": {
"amount": 250,
"currency": "EUR"
},
"status": "PAID",
"paidAt": "2026-07-15T09:12:00Z",
"payment": {
"code": "pi_3OqX8s2eZvKYlo2C",
"status": "PAYMENT_COLLECTED",
"processedBy": "TURNEO",
"viaPaymentLink": false
},
"cancellation": {
"cancelledBy": "Traveler",
"cancelledAt": "2026-07-10T14:30:00",
"cancelledReason": "Change of plans",
"cancellationFeeAmount": 25,
"cancellationFeeCurrency": "EUR",
"refundPercentage": 75
},
"reseller": {},
"resellerProperty": {},
"language": "en",
"travelerInformation": {
"email": "guest@example.com",
"firstName": "Alice",
"lastName": "Smith",
"phone": "+385911234567"
},
"conciergeDiscount": null,
"allowedUses": 5,
"remainingUses": 3,
"voucherCode": "7WF4MRY2KC8N",
"recipientEmail": "recipient@guest.example",
"recipientName": "Alex Example",
"extraFieldResponses": {
"aa1bb2cc-3dd4-4ee5-9ff6-0a1b2c3d4e5f": "Happy birthday!"
},
"createdAt": "2026-07-15T09:05:00Z"
}
],
"finalPrice": {
"amount": 250,
"currency": "EUR"
},
"basePrice": 200,
"resellerReference": "HOTEL-4711",
"emailNotification": [
"concierge@hotel.com"
],
"bookingSource": "hub",
"utmMedium": "email",
"utmSource": "newsletter",
"store": {
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"subdomain": "hotel-adriatic",
"name": "Hotel Adriatic Experiences"
},
"storeExtraFieldResponses": {
"0d2e4f6a-8b0c-4d2e-9f1a-3b5c7d9e1f2a": "Room 204",
"7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f": true
},
"createdAt": "2026-07-02T09:15:00Z",
"updatedAt": "2026-07-02T09:20:00Z"
}Errors
- 400
Validation failed. Inspect
errors[].fieldanderrors[].code.- 401
Missing or invalid
X-API-Keyheader.
Error body
typestringError class.
- Allowed values:
validation_errorclient_errorserver_error- Example:
validation_error
errorsobject[]Child fields
codestringMachine-readable error code.
- Example:
required
fieldstringnullableOffending field, or null/'general' for non-field errors.
- Example:
startTime
messagestringHuman-readable message.
- Example:
This field is required.
{
"type": "validation_error",
"errors": [
{
"code": "required",
"field": "startTime",
"message": "This field is required."
}
]
}