Skip to main content

Quote a return

POST 
/returns/quote

Prices a proposed return of lines of a paid order at the outlet in X-Outlet-ID, and shows which tenders can be refunded. Nothing is recorded and the answer is not binding.

Before you call​

  • The company needs a plan with returns.
  • With X-User-ID, the acting user needs the return permission and an open shift.
  • Without X-User-ID (MPOS-2389): you may quote a return of your own partner order with no acting user and no open shift. The call then runs as your order source, the same actor as POST /orders without a user. All of these must hold:
    • the order was created by your application's order source with POST /orders;
    • every refund_tenders row names your source's partner rail: the payment_method_id of the order's tender on that rail. Never cash, never another payment method;
    • the outlet needs no approval for returns.
    • Without refund_tenders, every tender of the order must be on that rail (the refund defaults to the original tenders).
  • Anything else without X-User-ID answers 400 USER_ID_REQUIRED. Exchanges always need X-User-ID and an open shift.
  • This call takes no Idempotency-Key.
  • An order of a kitchen sales type (dine_in, takeaway, pickup, delivery, qr_ordering) can be returned, refunded or exchanged only once its kitchen ticket is served or completed (kitchen_status on GET /orders/{id} is served or completed). Other sales types and the replacement order of an exchange are not affected.

Request​

  • refund_tenders is optional on a quote. When sent, each tender must name a refundable tender of eligible_refund_tenders.
  • On a partner order, a cash tender above the cash the order was paid with answers 422 PARTNER_REFUND_ORIGINAL_TENDER on the quote already. On a Dine In round, a tender above what its table settlement tender can still take answers 422 REFUND_TENDER_EXCEEDS_REMAINING on the quote already.
  • The other amount checks run when the return is created: an amount that is not above 0, the same payment method twice, more than one tender when the refund is not a full refund of an untouched order, and amounts that do not add up to the refund.

Behaviour​

  • A tender recorded without a payment method shows payment_method_id: null, refundable: false and reason: legacy_tender, and is never in suggested_refund_tenders.
  • A partner order (one created with POST /orders) is refunded to the original tender. On it, the Cash group shows refundable: false and reason: partner_original_tender unless the order was paid in cash; when it was, Cash is refundable up to the cash the order paid. A quote that sends a cash tender above that answers 422 PARTNER_REFUND_ORIGINAL_TENDER, as POST /returns does.
  • A Dine In table bill is several orders, one per round: return, refund or exchange one round at a time. Reverse the rounds a table settlement paid instead of the settlement itself.
  • A Dine In round paid through a table settlement lists its share of the settlement's tenders in eligible_refund_tenders.

Errors​

StatusCodeWhen
400VALIDATION_FAILEDThe body is not valid. A line that is not part of the order has a field error on lines[i].order_line_id with code NOT_FOUND (INVALID_FORMAT when the order_line_id is not a UUID).
400USER_ID_REQUIREDX-User-ID is missing, and the call is not your own partner order refunded to your rail with no approval (see Before you call).
403PLAN_FEATURE_REQUIREDThe plan has no returns. data.reason is not_in_plan or disabled (the merchant can turn it on in Settings > Features), and data.feature is the feature key. A missing Public API add-on answers the same code without data.
403PERMISSION_DENIEDThe acting user may not do this.
403OUTLET_FORBIDDENThe outlet is not allowed.
404NOT_FOUNDUnknown original order, or an order of another outlet.
409SHIFT_NOT_OPENYou sent X-User-ID and the user has no open shift.
409DINE_IN_ROUND_UNPAIDThe Dine In round's bill is not paid yet.
409SETTLEMENT_SALE_NOT_REVERSIBLEThe order is the payment record of a whole table (dine-in or online settlement).
409KITCHEN_NOT_FULFILLEDThe kitchen ticket is not served or completed, or there is no ticket; see data.kitchen_status (null when there is no ticket).
422UNPROCESSABLEA business rule failed, for example a terms payment order that is not settled.
422POST_SALE_DISABLEDThe merchant turned this operation off in the post-sale policy.
422POST_SALE_WINDOW_EXPIREDThe order is older than the policy allows; data.max_days is the limit in days.
422INVALID_USERThe acting user is not valid.
422REFUND_TENDER_NOT_ELIGIBLEA sent tender is not a refundable tender of eligible_refund_tenders.
422REFUND_TENDER_EXCEEDS_REMAININGA Dine In round asks more of one non-cash tender than it can still take.
422PARTNER_REFUND_ORIGINAL_TENDERA partner order: a sent cash tender is above the cash the order was paid with.

Request​

Responses​

The return quote