manage_order
Notes, stop, refund, billing.
One paid order. add_note (text, scan:write): a note on the order's chart ("I added an FAQ"); it never changes a score. billing_link (scan:read): Stripe's page to replace the card and see invoices, for the person to open. stop⚠ (order:write): no more checks or payments, can't be undone. request_refund⚠ (order:write; optional note, stop): asks ScanFree for the refund the policy gives; a person carries it out. order:write is off unless the person ticked it for this key or app. ⚠ answers needs_confirmation with a plain summary (checks left, the refund figure) and a confirm_token. Show the summary to the person first, and only if they agree call again with the same arguments plus confirm_token (works once, for 10 minutes). An agent never pays and never moves money.
Who can use it
- Access
- A paid order. stop and request_refund need the "Stop orders and ask for refunds" permission (order:write) and the person's confirmation.
- Scope
scan:readfor reading; each write action's scope is below.- Changes anything
- Its write actions do; see below.
Actions
Pass one in action.
| action | Scope | What it does |
|---|---|---|
billing_link | scan:read | Stripe's page for this order, where the person replaces the card and sees invoices. |
add_note | scan:write | A write action: the description above says what it changes. |
stop | order:write | A write action: the description above says what it changes. |
request_refund | order:write | A write action: the description above says what it changes. |
Inputs
| Name | Type | Required | Values and limits |
|---|---|---|---|
action | string | Yes | billing_link, add_note, stop, request_refund |
order_id | string | Yes | An order id from get_dashboard |
text | string | No | 0 to 200 characters. For add_note: 3 to 200 characters |
note | string | No | 0 to 1000 characters. For request_refund: why, for the person at ScanFree |
stop | boolean | No | For request_refund: also ask to stop the order |
confirm_token | string | No | Only for a ⚠ action, on the second call: the confirm_token from the first answer, after the person agreed |
What it answers
Every answer has status and, where useful, message in plain words.
| Field | Meaning |
|---|---|
url | billing_link: the page for the person to open; an agent can't act on it. |
status, summary, confirm_token | stop and request_refund: needs_confirmation with a plain summary (checks left, the refund figure) and a token; the second call with the token acts. |
state, message | What happened: noted, stopped, or the refund asked for (a person at ScanFree carries it out). |
Errors
| status | What it means |
|---|---|
invalid_input | order_id isn't an order id. Take one from get_dashboard. |
not_found | No order with that id on this account. |
forbidden | The key or app lacks order:write; missing_scope and grant_url say where to tick it. |
not_available | Nothing to stop (the order has ended), or billing isn't available; url points to the order page. |
invalid_input | A confirm_token that is wrong, used, expired or for other arguments. |
forbidden | The credential lacks the tool's scope, or an agent's owner has no ScanFree account yet (the owner signs in on the website once). |
Input validation error | An argument doesn't match the schema below. The call fails with MCP error -32602, naming the field. |
Errors before the tool runs (a missing key, too many requests) are on the MCP page.
Example
Example shape; values are illustrative.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "manage_order",
"arguments": {
"action": "billing_link",
"order_id": "00000000-0000-4000-8000-000000000002"
}
}
}{
"status": "ok",
"order_id": "00000000-0000-4000-8000-000000000002",
"url": "https://billing.stripe.com/…",
"message": "Stripe's page for this order: the person can replace the card and see invoices there. Give the link to the person; an agent can't act on it."
}