Refund a cancelled retail item

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

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

Retries the refund of a CANCELLED line, for example after the refund at cancellation failed. Pass cancellationFeeAmount to replace the fee recorded at cancellation, or omit it to keep that fee. Only card payments taken through Turneo (processedBy TURNEO or RESELLER_CARD) are refunded; for those, a line that is not CANCELLED, is already refunded, or would refund nothing returns 400. For any other payment method the call changes nothing. A payment provider failure returns 500 and can be retried.

Requestbash
curl -X POST "https://api.turneo.co/v2/retail-items/3HCX9KPT2L/refund" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{}'

Path parameters

  • idstringrequired

    The line's UUID or its retailCode.

    Example:
    3HCX9KPT2L

Request bodyapplication/json

  • cancellationFeeAmountnumber

    Fee to keep instead of the one recorded at cancellation. The refund (line price minus fee) must be positive.

    Example:
    5
Example: Retry with the fee recorded at cancellation
Retry with the fee recorded at cancellationjson
{}
Example: Refund all but 5.00
Refund all but 5.00json
{
  "cancellationFeeAmount": 5
}

Responses

200object

The line with its updated payment.

  • 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).

500

The payment provider failed. Nothing was refunded; the call can be retried.

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