Skip to main content

Quote an exchange

POST 
/exchanges/quote

Prices an exchange: lines taken back and replacement lines sold. Nothing is recorded and the answer is not binding.

Before you call​

  • The company needs a plan with exchanges.
  • An open shift is needed.
  • 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​

  • tenders is optional; without it payment_fee is not priced. The quote does not check that the tenders add up; POST /exchanges does (see its Request section for the three cases: pay the difference, refund the difference, keep the difference).
  • A tender names its payment method by payment_method_id: a cash or custom method from GET /payment-methods, the order's Terms Payment method, or the order source's own partner rail.
  • The own partner rail is the Paid on <display_name> method of the order source that sent the order with POST /orders. Only the app that owns that order source can use it.
  • GET /payment-methods does not list the rail. Its id is the payment_method_id on the order's tender (GET /orders/{id}), but only when the order was paid on that rail (an order sent without tenders; an order sent with its own tenders has no rail tender).
  • The rail of another order source, the order's rail named by another app, a rail on an order no source sent, and any other type (QRIS included) answer 400 VALIDATION_FAILED on the field with code NOT_ALLOWED.

Behaviour​

  • refund_amount is what goes back to the customer when the replacement costs less.
  • On a partner order (one created with POST /orders) Cash is not refundable unless the order was paid in cash: a cash tender on a refunded difference above the cash the order paid answers 422 PARTNER_REFUND_ORIGINAL_TENDER, as POST /exchanges 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.

Errors​

StatusCodeWhen
400VALIDATION_FAILEDThe body is not valid. A tender that is not allowed has code NOT_ALLOWED on the field. A returned line that is not part of the order has a field error on returned_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.
403PLAN_FEATURE_REQUIREDThe plan has no exchanges. 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_OPENThere is 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; read message.
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.
422PARTNER_REFUND_ORIGINAL_TENDERA partner order: a cash tender on a refunded difference is above the cash the order was paid with.
422PRICE_AMOUNT_OVERFLOWA replacement line's quantity, or the replacement total with its tax and fees, is too large to price.

Request​

Responses​

The exchange quote