Return a placed order, in two calls: a quote, then a confirm.
Connect to https://mcp.opencommerce.sh/mcp with your Commerce SDK credentials as Authorization: Bearer <YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>. See Connect your agent.
start_return isn’t available on the server yet. Until it is, a call answers order_actions_unavailable.
Behavior: Changes state on the second call only. The quote changes nothing and can be asked again. Never resend the confirm.
What it does
Returns a whole placed order in two calls. The first call, without confirm_token, returns a quote with the refund, the card it goes back to, a confirm_token, and its expires_at, and changes nothing. Show the shopper the refund and ask.Only after the shopper says yes to that quote, call again with the same reason and the quote’s confirm_token. That opens the return once and answers return_id. The labels and the refund come later: read them with get_return.
Inputs
Field
Type
Description
shopper_id(required)
string
Your own stable id for the shopper. The same value on every call for the same person.
order_id(required)
string
The order’s id, from a buy result, get_conversation, or an order update.
reason(required)
enum
Why the shopper sends it back, in their words mapped to one of the reasons listed under Notes.
notes
string
Anything else the shopper said about the problem, as they said it. 1 to 1000 characters.
confirm_token
string
The confirm_token from this order’s quote, only after the shopper said yes to that quote. Leave it out to get the quote.
merchant
string
Only when the error is order_id_ambiguous: one of the stores the error names.
Returns
Field
Type
Description
order_id
string
The order’s id.
action
string
cancel or return.
stage
string
quote: nothing changed yet, so show the shopper the refund and ask. confirmed: the store has the request.
refund
object or null
{ amount_cents, currency }: what goes back to the shopper.
refund_to
object or null
{ brand, last4 }: the card the refund goes back to. null when the order was paid from a balance.
items
array of strings
The order lines the action covers. Empty for the whole order.
confirm_token
string or null
On a quote: pass it back with the shopper’s yes. It acts once.
expires_at
string or null
On a quote: the time the token stops working.
state
string or null
Once confirmed. For a cancel: canceled, or requested while the store hasn’t confirmed. For a return: requested, label_ready, denied, or refunded.