Skip to main content
These tools mutate return state. They’re marked as destructive in the MCP protocol so well-behaved clients (Claude Desktop, Cursor, VS Code Copilot) prompt the merchant for confirmation before executing them.
Reject, cancel, close, and process actions are irreversible. The MCP server’s instructions tell the assistant to confirm before executing — but the responsibility for that confirmation ultimately sits with the client.
After most actions, the tool returns a Generative UI card showing the new return state alongside a short text summary, so the merchant can see immediately what happened.

​
Add Return Note

Tool name: add-return-note-tool  ·  Destructive  ·  Permissions: manage-returns Add an internal staff note to a return. Notes are visible to other staff members in the Loop Admin and do not impact return state.

​
Parameters

​
Example prompt

“Add a note to return #1234 that the customer called and wants to switch to a refund.”

​
Flag Return

Tool name: flag-return-tool  ·  Destructive  ·  Permissions: manage-returns Flag a return for manual review with optional QC reasons and a comment. The return must be in a flaggable state and not already flagged. At least one reason or a non-empty comment is required.

​
Parameters

​
Example prompt

“Flag return #1234 for damaged item — note that the box arrived crushed.”

​
Unflag Return

Tool name: unflag-return-tool  ·  Destructive  ·  Permissions: manage-returns Mark a flagged return as reviewed (unflag it). The return must currently be flagged.

​
Parameters

​
Example prompt

“Unflag return #1234 — I’ve reviewed it and it’s fine.”

​
Reject Return

Tool name: reject-return-tool  ·  Destructive  ·  Permissions: manage-returns Reject a return. This rejects all line items and closes the return. The return must be in open, partial, expired, or review state.
This action cannot be undone.

​
Parameters

​
Example prompt

“Reject return #1234 — the items aren’t eligible per our policy.”

​
Cancel Return

Tool name: cancel-return-tool  ·  Destructive  ·  Permissions: manage-returns Cancel a return and any associated exchanges, refunds, or gift cards. The return must be in open, partial, or expired state.
This action cannot be undone.

​
Parameters

​
Example prompt

“Cancel return #1234 — the customer changed their mind.”

​
Close Return

Tool name: close-return-tool  ·  Destructive  ·  Permissions: manage-returns Close a return by marking it as processed without taking any action in Shopify. No refunds, exchanges, or gift cards are issued.
This action cannot be undone. The customer will not be able to interact with the return after it is closed.

​
Parameters

​
Example prompt

“Close return #1234 without issuing anything — we already handled this manually.”

​
Process Return

Tool name: process-return-tool  ·  Destructive  ·  Permissions: manage-returns or manage-point-of-sale Process a return. This kicks off background jobs that issue exchanges, refunds, and gift cards. Processing happens asynchronously — the tool returns immediately, but downstream resolution may take a few moments.
The return must be in a processable state (typically after a label scan or after the merchant has reviewed line items).

​
Parameters

Omit exchange_actions and restock_actions to use the default behavior for every line item.

​
Example prompt

“Process return #1234 with the defaults.”