Update a booking order

PATCH/v2/booking-orders/{id}

Requires your API key in the X-API-Key header.

Partially updates order-level fields (travelerInformation, resellerReference, emailNotification, utmMedium, utmSource) and, optionally, patches individual bookings already in the order via the bookings array (each item needs the booking id; an id outside the order returns 400). This is how checkout fills in payment, traveler info, extra-field answers, meeting point and notes between reserve and confirm — bookings themselves can't be added or removed here, use .../add and .../remove for that.

Retail lines are patched the same way through the retailItems array, which carries the buyer's answers to each SKU's purchase questions.

Returns 400 if the order has already EXPIRED.

Requestbash
curl -X PATCH "https://api.turneo.co/v2/booking-orders/0f47ac10-b58c-4372-a567-0e02b2c3d479" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "travelerInformation": {
      "email": "alice@example.com",
      "firstName": "Alice"
    }
  }'

Path parameters

  • idstring (uuid)required

    UUID of the booking order.

    Example:
    0f47ac10-b58c-4372-a567-0e02b2c3d479

Request bodyapplication/json, required

  • travelerInformationobject

    Traveler 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
    • firstNamestringnullable

      Traveler's first name.

      Example:
      Alice
    • lastNamestringnullable

      Traveler's last name.

      Example:
      Smith
    • phonestringnullable

      Traveler's phone number in international format.

      Example:
      +385911234567
  • resellerReferencestring

    Reseller's internal order reference.

    Limits:
    up to 128 characters
    Example:
    HOTEL-4711
  • emailNotificationstring (email)[]

    Email addresses to notify about the order.

  • utmMediumstring

    UTM medium tracking parameter.

    Limits:
    up to 128 characters
    Example:
    email
  • utmSourcestring

    UTM source tracking parameter.

    Limits:
    up to 128 characters
    Example:
    newsletter
  • storeExtraFieldResponsesobject[]

    Answers to the store's checkout questions — asked once per order, not per booking. Sent as a list, stored and read back as a {questionId: response} map, and copied onto every non-removed booking and active retail line of the order. Replaces the stored map; an empty list is a valid clear and propagates the same way, emptying the map on the order and on all of those bookings and retail lines. Ids are not checked against the store's current questions; only the value types are validated here. Required questions are enforced later, at POST /v2/booking-orders/{id}/confirm, which returns 400 when one is unanswered — but enforcement is skipped when the store cannot be resolved (the order carries no store, or its config is unreachable) and for payment-link orders (payment.viaPaymentLink), whose answers were already validated when the link was created and whose payment page cannot collect a question added while the link was outstanding. Clients should not rely on the gate as their only guard.

    Child fields
    • fieldIdstringrequired

      Id of a question defined on the store config (checkout.questions); a client-generated UUID in practice.

      Limits:
      up to 64 characters
      Example:
      0d2e4f6a-8b0c-4d2e-9f1a-3b5c7d9e1f2a
    • responseanyrequired

      The traveler's answer: a string for QUESTION questions, a boolean for CHECKBOX questions, or null when unanswered. The key must be present. Any other JSON type is a 400. A false checkbox is a real answer (exported as No); only null and "" count as unanswered.

      Example:
      Room 204
  • bookingsobject[]

    Patches for bookings that already belong to the order.

    Child fields
    • idstring (uuid)required

      UUID of the booking to patch. Must belong to this order, otherwise 400.

      Example:
      7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a
    • paymentobjectnullable

      Payment patch — validated as sent, then merged key-by-key onto the stored payment object (existing keys not present in the patch survive).

      Child fields
      • codestringnullable

        Payment reference — e.g. a Stripe payment-intent id, sent by the client at confirm time.

        Example:
        pi_3OqX8s2eZvKYlo2C
      • statusstring

        Payment status.

        Allowed values:
        PAYMENT_PENDINGPAYMENT_COLLECTEDREFUNDEDFREE
        Example:
        PAYMENT_COLLECTED
      • processedBystringnullable

        Who 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 payment at confirm, with the voucher code as code).

        Example:
        TURNEO
      • viaPaymentLinkboolean

        Present and true when the payment was initiated through a payment link.

        Example:
        false
    • resellerReferencestringnullable

      Reseller's internal reference for this booking.

      Limits:
      up to 128 characters
      Example:
      HOTEL-4711
    • resellerPropertystring (uuid)nullable

      UUID of the reseller property (hotel) to attribute the booking to. Must be one of the booking reseller's properties, otherwise 400. Null clears it.

      Example:
      4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a
    • pmsBookingIdstringnullable

      External PMS reservation id to link to this booking.

      Limits:
      up to 128 characters
      Example:
      123456789
    • metadataobject

      Metadata patch, merged onto the booking's existing metadata.

    • travelerInformationobject

      Traveler-info patch, merged onto the booking's existing traveler information.

      Child fields
      • emailstring (email)

        Traveler's email address — used for confirmation, ticket and payment-link emails.

        Example:
        guest@example.com
      • firstNamestringnullable

        Traveler's first name.

        Example:
        Alice
      • lastNamestringnullable

        Traveler's last name.

        Example:
        Smith
      • phonestringnullable

        Traveler's phone number in international format.

        Example:
        +385911234567
    • extraFieldResponsesobject[]

      Answers to the option's extra fields. Each fieldId must belong to the booking's option. Replaces the stored response set.

      Child fields
      • fieldIdstring (uuid)required

        UUID of an active extra field on the booking's option.

        Example:
        aa1bb2cc-3dd4-4ee5-9ff6-0a1b2c3d4e5f
      • responsestringrequired

        The traveler's answer. For checkbox fields use "true"/"false".

        Example:
        Vegetarian
    • notesobject

      Booking notes keyed by author (fromSeller, fromOrganizer).

    • meetingPointIdstring (uuid)nullable

      UUID of one of the experience's predefined meeting points.

      Example:
      6e5f4a3b-2c1d-4e0f-9a8b-7c6d5e4f3a2b
    • meetingPointobjectnullable

      Custom pickup location, used when meetingPointId is not supplied.

    • resellerobject

      Store/agent attribution merged into the booking metadata.

  • retailItemsobject[]

    Patches for retail lines that already belong to the order, typically the buyer's answers to a SKU's purchase questions.

    Child fields
    • idstring (uuid)required

      UUID of the retail line. A line outside this order returns 400 (ORDER_RETAIL_ITEM_NOT_FOUND).

      Example:
      7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a
    • extraFieldResponsesobject[]

      Answers to the SKU's questions. Replaces the stored answers. Each fieldId must be a question of this line's SKU, otherwise 400 (RETAIL_EXTRA_FIELD_UNAVAILABLE).

      Child fields
      • fieldIdstring (uuid)required

        UUID of a question on the line's SKU.

        Example:
        aa1bb2cc-3dd4-4ee5-9ff6-0a1b2c3d4e5f
      • responsestringrequired

        The buyer's answer. For checkbox questions use "true"/"false".

        Example:
        Happy birthday!
Example: Update traveler info only
Update traveler info onlyjson
{
  "travelerInformation": {
    "email": "alice@example.com",
    "firstName": "Alice"
  }
}
Example: Answer required extra fields on one booking
Answer required extra fields on one bookingjson
{
  "bookings": [
    {
      "id": "7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a",
      "extraFieldResponses": [
        {
          "fieldId": "aa1bb2cc-3dd4-4ee5-9ff6-0a1b2c3d4e5f",
          "response": "Vegetarian"
        }
      ]
    }
  ]
}
Example: Answer a retail SKU's purchase question
Answer a retail SKU's purchase questionjson
{
  "retailItems": [
    {
      "id": "6c7d8e9f-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
      "extraFieldResponses": [
        {
          "fieldId": "bb2cc3dd-4ee5-4ff6-8a7b-1c2d3e4f5a6b",
          "response": "Happy birthday!"
        }
      ]
    }
  ]
}

Responses

200object

The updated order with embedded bookings.

  • idstring (uuid)

    Order UUID.

    Example:
    0f47ac10-b58c-4372-a567-0e02b2c3d479
  • statusstring

    Derived 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
  • travelerInformationobjectnullable

    Traveler 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
    • firstNamestringnullable

      Traveler's first name.

      Example:
      Alice
    • lastNamestringnullable

      Traveler's last name.

      Example:
      Smith
    • phonestringnullable

      Traveler'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
    • bookingCodestring

      Short human-readable booking code used on tickets and folios.

      Example:
      TRN-8F3K2A
    • bookingStatusstring

      Booking 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
    • experienceobjectnullable

      Full embedded experience object (id, name, images, location, duration, refund policy, organizer...). Shape matches the v2 experience read schema.

    • optionobjectnullable

      Full 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)nullable

      The gift voucher's retail item this booking is redeemed with, or null.

      Example:
      6c7d8e9f-0a1b-4c2d-8e3f-4a5b6c7d8e9f
    • slotStartTimeobjectnullable

      A local date/time pair in the experience's timezone.

      Child fields
      • datestring (date)nullable

        Local date (YYYY-MM-DD).

        Example:
        2026-07-10
      • timestringnullable

        Local time of day (HH:MM:SS). Null for date-only (all-day) slots.

        Example:
        10:00:00
    • slotEndTimeobjectnullable

      Booking 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)nullable

        Local date (YYYY-MM-DD).

        Example:
        2026-07-10
      • timestringnullable

        Local time of day (HH:MM:SS). Null for date-only (all-day) slots.

        Example:
        10:00:00
    • timestring (date-time)nullable

      Booking start as a UTC timestamp.

      Example:
      2026-07-10T08:00:00Z
    • participantCountsmap of integer

      Map of participant-type UUID to booked head count.

    • totalParticipantsinteger

      Total booked participants across all participant types.

      Example:
      2
    • bookedDurationobject

      Booked duration as {days, hours, minutes}, computed from the option configuration.

    • durationUnitsintegernullable

      Number 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
      • addonNamestring

        Add-on name in the request language.

        Example:
        Hotel transfer
      • quantityinteger

        Effective booked quantity (server-derived for per-person checkbox add-ons).

        Example:
        2
      • pricestringnullable

        Unit price of the add-on as a decimal string.

        Example:
        15.00
      • perPersonboolean

        Whether the add-on is priced per person.

        Example:
        true
    • extraFieldResponsesmap of stringnullable

      Map of extra-field UUID to the traveler's answer.

    • storeExtraFieldResponsesobjectnullable

      Answers 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[]nullable

      Alternative 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)nullable

        Local start date of the alternative slot.

        Example:
        2026-07-11
      • startTimestringnullable

        Local start time of the alternative slot.

        Example:
        14:00:00
    • resellerobject

      Embedded reseller partner (id, name, logo...) enriched with attribution from the booking metadata — storeId, storeName, storeSubdomain, agentName, agentReference, hotelName, roomNumber — when present.

    • finalPriceobject

      Total retail price the traveler pays for this booking.

      Child fields
      • amountnumber

        Amount in major currency units.

        Example:
        250
      • currencystring

        ISO 4217 currency code.

        Example:
        EUR
    • basePriceobject

      Base (pre-commission) price of the booking.

      Child fields
      • amountnumber

        Amount in major currency units.

        Example:
        250
      • currencystring

        ISO 4217 currency code.

        Example:
        EUR
    • netRateobject

      Organizer's payout amount for this booking.

      Child fields
      • amountnumber

        Amount in major currency units.

        Example:
        250
      • currencystring

        ISO 4217 currency code.

        Example:
        EUR
    • discountobjectnullable

      Automatic slot/option discount applied at booking time, or null.

    • voucherobjectnullable

      Applied voucher details (code, discount), or null when no voucher is applied.

    • conciergeDiscountobjectnullable

      Manually applied concierge discount (amount, note), or null.

    • paymentobjectnullable

      Payment details for one booking.

      Child fields
      • codestringnullable

        Payment reference — e.g. a Stripe payment-intent id, sent by the client at confirm time.

        Example:
        pi_3OqX8s2eZvKYlo2C
      • statusstring

        Payment status.

        Allowed values:
        PAYMENT_PENDINGPAYMENT_COLLECTEDREFUNDEDFREE
        Example:
        PAYMENT_COLLECTED
      • processedBystringnullable

        Who 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 payment at confirm, with the voucher code as code).

        Example:
        TURNEO
      • viaPaymentLinkboolean

        Present and true when the payment was initiated through a payment link.

        Example:
        false
    • travelerInformationobjectnullable

      Booking-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
      • firstNamestringnullable

        Traveler's first name.

        Example:
        Alice
      • lastNamestringnullable

        Traveler's last name.

        Example:
        Smith
      • phonestringnullable

        Traveler's phone number in international format.

        Example:
        +385911234567
    • meetingPointobjectnullable

      Resolved meeting point / pickup details for the booking.

    • resellerReferencestringnullable

      Reseller's internal reference for this booking.

      Example:
      HOTEL-4711
    • resellerPropertyobjectnullable

      The reseller property (hotel) the booking is attributed to — id, name, location, partner, parentProperty, roomCount and a pmsIntegration summary — or null.

    • pmsBookingIdstringnullable

      External PMS reservation id linked to this booking (e.g. Valamar master id).

      Example:
      123456789
    • bookingSourcestringnullable

      Source identifier of the sales channel that created the booking.

      Example:
      hub
    • emailNotificationstring (email)[]nullable

      Extra email addresses notified about this booking.

    • metadataobjectnullable

      Arbitrary attribution metadata (store/agent details, external provider ids).

    • languagestring

      Language code used for traveler-facing communication.

      Example:
      en
    • cancellationobjectnullable

      Cancellation details (cancelledBy, cancelledAt, cancellationFeeAmount), or null.

    • reviewobjectnullable

      The 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
      • namestring

        Resource display name.

        Example:
        Kayak guide Ivan
    • notesobjectnullable

      Booking 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. voucherCode is 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
    • retailCodestring

      Short 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
    • skuCodestringnullable

      The purchased SKU's stock-keeping code.

      Example:
      TSHIRT-RED-M
    • experienceIdstring (uuid)

      UUID of the retail product.

      Example:
      0d4dbb2e-8a51-4a4b-9d3e-6f2b7c1a9e55
    • experienceobject

      The retail product, in the experience read shape without the fields that only bookable experiences have (options, participant types, meeting points, booking type).

    • quantityinteger

      Units bought. Always 1 on a gift voucher line.

      Example:
      2
    • imageUrlstring (uri)nullable

      The 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.

    • finalPriceobject

      What the buyer pays for the line (unit price times quantity, minus any concierge discount).

      Child fields
      • amountnumber

        Amount in major currency units.

        Example:
        250
      • currencystring

        ISO 4217 currency code.

        Example:
        EUR
    • netRateobject

      What the product's organizer receives for the line (line total minus commission).

      Child fields
      • amountnumber

        Amount in major currency units.

        Example:
        250
      • currencystring

        ISO 4217 currency code.

        Example:
        EUR
    • statusstring

      ON_HOLD while the order is unconfirmed; PAID once it is confirmed; DELIVERED after you mark it delivered; CANCELLED after a cancellation. EXPIRED means the order's hold ran out, REMOVED that the line was taken out of the order.

      Allowed values:
      ON_HOLDPAIDDELIVEREDCANCELLEDEXPIREDREMOVED
      Example:
      PAID
    • paidAtstring (date-time)nullable

      When the order was confirmed. Retail has no service date, so reporting uses this.

      Example:
      2026-07-15T09:12:00Z
    • paymentobjectnullable

      Payment details for one booking.

      Child fields
      • codestringnullable

        Payment reference — e.g. a Stripe payment-intent id, sent by the client at confirm time.

        Example:
        pi_3OqX8s2eZvKYlo2C
      • statusstring

        Payment status.

        Allowed values:
        PAYMENT_PENDINGPAYMENT_COLLECTEDREFUNDEDFREE
        Example:
        PAYMENT_COLLECTED
      • processedBystringnullable

        Who 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 payment at confirm, with the voucher code as code).

        Example:
        TURNEO
      • viaPaymentLinkboolean

        Present and true when the payment was initiated through a payment link.

        Example:
        false
    • cancellationobjectnullable

      Cancellation details (cancelledBy, cancelledAt in UTC, cancelledReason, cancellationFeeAmount, cancellationFeeCurrency). Null unless the line is CANCELLED.

      Child fields
      • cancelledBystring

        Who cancelled the booking.

        Allowed values:
        TravelerOrganizerResellerAdmin
        Example:
        Traveler
      • cancelledAtstring

        When the cancellation happened, as a naive local timestamp in the experience's timezone.

        Example:
        2026-07-10T14:30:00
      • cancelledReasonstringnullable

        Free-text reason supplied by the canceller.

        Example:
        Change of plans
      • cancellationFeeAmountnumber

        Fee retained from the traveler. 0 means a full refund; the full price means non-refundable.

        Example:
        25
      • cancellationFeeCurrencystring

        Currency of the cancellation fee (the booking's currency).

        Example:
        EUR
      • refundPercentagenumber

        The 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
    • resellerobjectnullable

      The selling partner, enriched with the store and agent attribution captured at checkout.

    • resellerPropertyobjectnullable

      The property (hotel) the sale is attributed to, or null.

    • languagestringnullable

      Language of the buyer's checkout, used for emails and labels.

      Example:
      en
    • travelerInformationobjectnullable

      The 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
      • firstNamestringnullable

        Traveler's first name.

        Example:
        Alice
      • lastNamestringnullable

        Traveler's last name.

        Example:
        Smith
      • phonestringnullable

        Traveler's phone number in international format.

        Example:
        +385911234567
    • conciergeDiscountobjectnullable

      Discount applied to the line at checkout, as {amount, currency, note}, or null.

    • allowedUsesintegernullable

      Total uses a gift voucher line grants. Null on other lines.

      Example:
      5
    • remainingUsesintegernullable

      Uses a gift voucher line has left; 0 unless the line is PAID. Null on other lines.

      Example:
      3
    • voucherCodestringnullable

      The gift voucher code. Returned only by the /v2/retail-items endpoints, 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)nullable

      Gift recipient of a voucher. The voucher email goes here instead of to the buyer.

      Example:
      recipient@guest.example
    • recipientNamestringnullable

      Name of the gift recipient.

      Example:
      Alex Example
    • extraFieldResponsesobjectnullable

      The 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
  • finalPriceobject

    Sum 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
    • amountnumber

      Amount in major currency units.

      Example:
      250
    • currencystring

      ISO 4217 currency code.

      Example:
      EUR
  • basePricenumber

    Sum of the base (net-rate) prices of the displayed bookings and retail lines, rounded to 2 decimals.

    Example:
    200
  • resellerReferencestringnullable

    Reseller's internal order reference.

    Example:
    HOTEL-4711
  • emailNotificationstring (email)[]nullable

    Email addresses to notify about the order; inherited by bookings without their own list.

  • bookingSourcestringnullable

    Source identifier of the sales channel (e.g. store subdomain, "hub").

    Example:
    hub
  • utmMediumstringnullable

    UTM medium tracking parameter captured at checkout.

    Example:
    email
  • utmSourcestringnullable

    UTM source tracking parameter captured at checkout.

    Example:
    newsletter
  • storeobject

    Store attribution derived from the first booking's metadata. All fields are null when the order was not placed through a store.

    Child fields
    • idstringnullable

      Store identifier (MongoDB id) the order was placed through.

      Example:
      64f1a2b3c4d5e6f7a8b9c0d1
    • subdomainstringnullable

      Store subdomain.

      Example:
      hotel-adriatic
    • namestringnullable

      Store display name.

      Example:
      Hotel Adriatic Experiences
  • storeExtraFieldResponsesobjectnullable

    Answers 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
Response 200json
{
  "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[].field and errors[].code.

401

Missing or invalid X-API-Key header.

404

The resource does not exist or belongs to another partner (existence is not leaked across partners).

Error body
  • typestring

    Error class.

    Allowed values:
    validation_errorclient_errorserver_error
    Example:
    validation_error
  • errorsobject[]
    Child fields
    • codestring

      Machine-readable error code.

      Example:
      required
    • fieldstringnullable

      Offending field, or null/'general' for non-field errors.

      Example:
      startTime
    • messagestring

      Human-readable message.

      Example:
      This field is required.
Response 400json
{
  "type": "validation_error",
  "errors": [
    {
      "code": "required",
      "field": "startTime",
      "message": "This field is required."
    }
  ]
}