Skip to content

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:read for reading; each write action's scope is below.
Changes anything
Its write actions do; see below.

Actions

Pass one in action.

actionScopeWhat it does
billing_linkscan:readStripe's page for this order, where the person replaces the card and sees invoices.
add_notescan:writeA write action: the description above says what it changes.
stoporder:writeA write action: the description above says what it changes.
request_refundorder:writeA write action: the description above says what it changes.

Inputs

NameTypeRequiredValues and limits
actionstringYesbilling_link, add_note, stop, request_refund
order_idstringYesAn order id from get_dashboard
textstringNo0 to 200 characters. For add_note: 3 to 200 characters
notestringNo0 to 1000 characters. For request_refund: why, for the person at ScanFree
stopbooleanNoFor request_refund: also ask to stop the order
confirm_tokenstringNoOnly 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.

FieldMeaning
urlbilling_link: the page for the person to open; an agent can't act on it.
status, summary, confirm_tokenstop 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, messageWhat happened: noted, stopped, or the refund asked for (a person at ScanFree carries it out).

Errors

statusWhat it means
invalid_inputorder_id isn't an order id. Take one from get_dashboard.
not_foundNo order with that id on this account.
forbiddenThe key or app lacks order:write; missing_scope and grant_url say where to tick it.
not_availableNothing to stop (the order has ended), or billing isn't available; url points to the order page.
invalid_inputA confirm_token that is wrong, used, expired or for other arguments.
forbiddenThe 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 errorAn 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.

The call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "manage_order",
    "arguments": {
      "action": "billing_link",
      "order_id": "00000000-0000-4000-8000-000000000002"
    }
  }
}
The answer (structured content)
{
  "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."
}