store/refund-order records a refund against an order, in whole or in part, and optionally puts the items back into stock. It refuses without confirm: true.
It records the refund. It does not move any money.
Before you run it
This records a refund in WooCommerce. It does not send money back through the payment provider — that has to be done in the provider’s own dashboard. A refund recorded here and not issued there leaves the books saying the customer was paid when they were not. The response says so explicitly, so that nobody reads a success as “the customer has their money”.
At a glance
| Ability | store/refund-order |
| Toolset | WooCommerce — toolset/woocommerce |
| Group | WooCommerce › Orders & Refunds |
| Requires | WooCommerce, active on the site |
| Capability | manage_options |
| Safety | Destructive — records a refund that cannot be reversed, and refuses to run without confirm: true. |
| Repeatable | Not idempotent — each call changes the row set, so re-running is not a no-op |
| Ships in | AcrossAI Abilities Manager 0.0.34 and later |
How it works
WooCommerce’s refund record and the payment provider’s refund are two separate things. Some gateways can be told to refund from within WooCommerce; many cannot, and the refund then exists only as a line in the order.
This ability deliberately does only the recording half. Attempting the gateway half would mean an assistant moving money through a payment provider, which is not a thing to do on the strength of a sentence — and doing it partially, for the gateways that support it, would be worse than not doing it at all, because the behaviour would depend on which provider the shop happens to use.
So the response states plainly that the money has not been sent. Issue it in the provider’s dashboard.
Refunding more than is left un-refunded is refused. Partial refunds accumulate, and the remaining balance is what the check runs against.
Restocking is optional and off by default, because a returned item is not always a sellable one.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
id | integer | Yes | Order ID. |
amount | string | No | Amount to refund. Omit to refund everything not already refunded. |
reason | string | No | Reason, recorded on the refund. |
restock_items | boolean | No — defaults to false | Put the refunded items back into stock. |
confirm | boolean | Yes — must be true | The irreversibility gate. Without it the call is refused before anything is touched. |
What comes back
| Name | Type | What it is |
|---|---|---|
refund_id | integer | The refund record created. |
amount | string | The amount recorded. |
restocked | boolean | Whether items were returned to stock. |
order | object | The order after the refund. |
note | string | The statement that no money has been sent through the payment provider. |
success | boolean | Whether the call completed. |
message | string | A one-line summary of what happened, suitable for showing a human. |
error_code | string | Present only on failure — a stable machine-readable reason, such as a missing field, a wrong field type or an unmet confirmation. |
Example
Ask your assistant:
Refund £24 on order 4471 — the customer returned one item.
It resolves to one call:
{
"ability": "store/refund-order",
"parameters": {
"id": 4471,
"amount": "24.00",
"reason": "Returned item",
"restock_items": true,
"confirm": true
}
}Worth knowing
- No money is sent. Issue the refund in the payment provider’s dashboard as well.
- Refunding more than remains un-refunded is refused.
- Restocking is off by default — a returned item is not always sellable.
- The refund record cannot be removed from here.
Related abilities
- Get Order — check what is already refunded
- List Order Notes — check whether the gateway refund happened
- Adjust Stock — restock manually instead
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category