List retail items

GET/v2/retail-items

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

Returns the retail and gift voucher lines on your products, plus the lines you sold of other partners' products, newest first. Every status is included, unconfirmed cart lines too, so filter with status=PAID,DELIVERED for completed sales. Filters combine; comma-separated values are ORed; paidAt and createdAt also take [gte], [lte], [gt], [lt] and [eq], e.g. ?paidAt[gte]=2026-07-01T00:00:00Z. Gift voucher lines include their voucherCode here.

Requestbash
curl "https://api.turneo.co/v2/retail-items" \
  -H "X-API-Key: <your-api-key>"

Query parameters

  • pageinteger

    Page number to return (1-based).

    Default:
    1
    Example:
    1
  • page_sizeinteger

    Number of lines per page (default 50).

    Default:
    50
    Example:
    50
  • nopaginationboolean

    When true, disables pagination and returns all matching lines in a plain array.

    Example:
    false
  • orderingstring

    Sort field, - prefix for descending. These are snake_case field names. Defaults to newest first.

    Allowed values:
    paid_at-paid_atcreated_at-created_atupdated_at-updated_at
    Example:
    -paid_at
  • statusstring

    Comma-separated line statuses: ON_HOLD, PAID, DELIVERED, CANCELLED, EXPIRED, REMOVED.

    Example:
    PAID,DELIVERED
  • experienceTypestring

    Comma-separated RETAIL and/or VOUCHER, to separate product sales from gift voucher sales.

    Example:
    VOUCHER
  • experienceIdstring

    Comma-separated product UUIDs. A malformed UUID returns 400.

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

    Comma-separated SKU UUIDs. A malformed UUID returns 400.

    Example:
    8f14e45f-ceea-4e5b-b0d4-9f3c1a2b3c4d
  • orderIdstring

    Comma-separated order UUIDs. A malformed UUID returns 400.

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

    Comma-separated partner ids of the sellers.

    Example:
    hotel-partner-1
  • retailCodestring

    Comma-separated retailCode references.

    Example:
    3HCX9KPT2L
  • travelerEmailstring (email)

    Buyer's email, case-insensitive exact match. The buyer is recorded on the order.

    Example:
    guest@example.com
  • consumerEmailstring (email)

    Who can use a gift voucher, case-insensitive exact match. Matches the gift recipient, or the buyer when the voucher was bought without a recipient, so a voucher gifted to someone else does not show up under the buyer's email.

    Example:
    recipient@guest.example
  • paidAtstring (date-time)

    Sale timestamp filter. Also accepts paidAt[gte], paidAt[lte], paidAt[gt], paidAt[lt] and paidAt[eq].

    Example:
    2026-07-01T00:00:00Z
  • createdAtstring (date-time)

    Creation timestamp filter, with the same bracket forms as paidAt.

    Example:
    2026-07-01T00:00:00Z

Responses

200object

Paginated list of retail items.

  • countinteger

    Total number of matching lines.

    Example:
    128
  • nextstring (uri)nullable

    URL of the next page, or null on the last page.

    Example:
    https://api.turneo.co/v2/retail-items?page=2&page_size=50
  • previousstring (uri)nullable

    URL of the previous page, or null on the first page.

  • resultsobject[]

    Retail items on this page.

    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
Response 200json
{
  "count": 128,
  "next": "https://api.turneo.co/v2/retail-items?page=2&page_size=50",
  "previous": null,
  "results": [
    {
      "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"
    }
  ]
}

Errors

400

Validation failed. Inspect errors[].field and errors[].code.

401

Missing or invalid X-API-Key header.

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."
    }
  ]
}