Cancel a retail item
POST/v2/retail-items/{id}/cancel
Requires your API key in the X-API-Key header.
Cancels a PAID or DELIVERED line; any other status returns 400
(RETAIL_ITEM_NOT_CANCELLABLE). The line becomes CANCELLED, counted stock goes back on the
shelf, and the buyer gets a cancellation email; a cancelled gift voucher's code stops working.
Card payments taken through Turneo are refunded minus cancellationFeeAmount (default 0, a full
refund; it can't be negative or exceed the line price). Payments the seller collected directly
are marked REFUNDED when the fee is 0. If the refund fails the cancellation still stands;
retry with POST /v2/retail-items/{id}/refund.
curl -X POST "https://api.turneo.co/v2/retail-items/7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a/cancel" \
-H "X-API-Key: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"cancelledReason": "Out of stock"
}'Path parameters
idstring (uuid)requiredThe line's UUID. The
retailCodeis not accepted here.- Example:
7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a
Request bodyapplication/json
cancellationFeeAmountnumberAmount kept from the line price. Can't exceed the price; a fee equal to the price cancels without a refund.
- Limits:
- minimum 0
- Default:
0- Example:
5
cancelledReasonstringnullableFree-text reason stored with the cancellation.
- Example:
Out of stock
Example: Cancel and refund in full
{
"cancelledReason": "Out of stock"
}Example: Keep a fee
{
"cancellationFeeAmount": 5,
"cancelledReason": "Opened item returned"
}Responses
200object
The cancelled line.
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
{
"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[].fieldanderrors[].code.- 401
Missing or invalid
X-API-Keyheader.- 404
The resource does not exist or belongs to another partner (existence is not leaked across partners).
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."
}
]
}