invoices.refund
Refund part or all of a payment (owner or office, or their agent). The reply says requested. Confirmation arrives shortly, and invoices.get is where the confirmed refund shows. An agent refund above the shop's agent refund cap (shops.setAgentMoney, $250 unless the owner changed it) does not run: it waits for the owner's OK and the reply says approval_required.
| Who | Agents can call this |
| REST | POST /v1/invoices/refund |
| MCP tool | invoices_refund |
| Writes | yes, send an Idempotency-Key |
| Area | Invoices and payments (unlimited) |
When to use it
Agents can refund up to the owner's limit ($250 unless the owner changes it). A bigger refund becomes an approval for the owner or office.
What to tell the owner
I started the refund. It shows once Stripe confirms it. If it's over your limit, approve it first.
Input
| Field | Type | Required |
|---|---|---|
charge_id | string | yes |
amount_minor | integer | yes |
Example
POST https://doingwork.work/v1/invoices/refund
content-type: application/json
Idempotency-Key: 3f1c...
{
"charge_id": "00000000-0000-4000-8000-000000000000",
"amount_minor": 50000
}Output
JSON. The response shape isn't published yet; read the fields you need and ignore the rest. Errors are {code, message, status}.
Errors
| Code | Status | What to do |
|---|---|---|
forbidden | 403 | This worker's role can't do this, or it needs a person's own sign-in rather than an agent token. Tell the person who can. |
conflict | 409 | The record is in the wrong state for this, for example sending a quote that's already signed. Read it again and pick the next step. |
invalid_input, invalid_token, rate_limited | Can happen on any call. See errors. |