Mark a retail item as delivered

POST/v2/retail-items/{id}/deliver

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

Marks a PAID line DELIVERED once the buyer has the goods. Any other status returns 400 (RETAIL_ITEM_NOT_DELIVERABLE). No request body. Money is unaffected and the line can still be cancelled afterwards. Leave gift voucher lines PAID: only a PAID voucher can be redeemed.

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

Path parameters

  • idstringrequired

    The line's UUID or its retailCode.

    Example:
    3HCX9KPT2L

Responses

200object

The line, now DELIVERED.

  • 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
{
  "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.

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