WooCommerce 11.1 adds a REST refund preview endpoint and compute_totals behavior. Support tools and integrations can calculate a refund before creating it, but tax rounding, shipping, fees, quantities, currency, permissions, retries, and changing order state can make the preview disagree with the eventual refund.
Use this for WooCommerce support tools, ERPs, returns portals, custom admin apps, and API clients that calculate or create refunds.
Quick answer
Build reconciled orders with simple, variable, taxed, discounted, shipped, fee-bearing, multi-quantity, and partially refunded lines. Call the preview endpoint with explicit quantities and amounts. Prove it creates no refund, note, stock change, gateway request, email, or analytics event. Then create one controlled refund from the same versioned order snapshot and compare line totals, tax, shipping, fees, currency, reason, and final amount.
What to check first
- Record WooCommerce version, order version, currency decimals, tax settings, payment method, permissions, and API client version.
- Create known orders covering coupons, tax classes, shipping tax, fees, quantities, partial refunds, and prior refunds.
- Call preview repeatedly and prove order rows, stock, notes, gateway, email, webhooks, and analytics remain unchanged.
- Change the order between preview and creation to test stale totals, concurrency, and idempotency keys.
- Compare preview, created refund, gateway record, order totals, stock, email, webhook, and finance export.
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Freeze a reconciled order snapshot and currency contract. | Record WooCommerce version, order version, currency decimals, tax settings, payment method, permissions, and API client version. | Preview requests produce no financial or inventory side effects. |
| Keep preview read-only and record a request fingerprint. | Create known orders covering coupons, tax classes, shipping tax, fees, quantities, partial refunds, and prior refunds. | Repeated previews return stable totals for the same order snapshot. |
| Require a fresh preview or explicit conflict when the order version changes. | Call preview repeatedly and prove order rows, stock, notes, gateway, email, webhooks, and analytics remain unchanged. | Stale previews cannot silently create against changed order state. |
| Use one idempotency key for the approved creation request. | Change the order between preview and creation to test stale totals, concurrency, and idempotency keys. | Created refund, gateway, stock, email, webhook, and finance export reconcile. |
Why this usually happens
- Tax and discount allocation can round at line or order level.
- A preview can become stale when another operator changes the order.
- Retries can be mistaken for permission to create a second refund.
- Gateway and WooCommerce amounts may use different minor-unit conventions.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
case,order_version,preview,side_effects,create,gateway,order,result
P1,v4,42.18,0,none,none,unchanged,pass
P2,v4,42.18,0,none,none,unchanged,pass
P3,v4,42.18,0,v5-conflict,none,unchanged,pass
P4,v5,39.00,0,R-88,39.00,39.00,pass
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Preview only | Partial line and tax | Totals returned, no side effect |
| Repeated preview | Same request and order version | Same result, no records |
| Stale preview | Order changed before create | Conflict or required recompute |
| Create refund | Approved preview snapshot | Gateway and order match |
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Freeze a reconciled order snapshot and currency contract.
- Keep preview read-only and record a request fingerprint.
- Require a fresh preview or explicit conflict when the order version changes.
- Use one idempotency key for the approved creation request.
- Reconcile WooCommerce, gateway, stock, email, webhook, and finance records.
Decision rule
Create a refund only from a current order snapshot when preview totals reconcile, the caller has creation permission, and the idempotency key has no prior successful refund.
Production verification checklist
- Preview requests produce no financial or inventory side effects.
- Repeated previews return stable totals for the same order snapshot.
- Stale previews cannot silently create against changed order state.
- Created refund, gateway, stock, email, webhook, and finance export reconcile.
Field notes
- Use a gateway sandbox and synthetic order.
- Record currency values in minor units when the API contract requires it.
- Keep preview and creation permissions separate where possible.
Questions teams ask during testing
Can this be tested on production?
Use production for read-only confirmation and one narrow synthetic fixture that cannot charge a card, email a real customer, expose personal data, or change inventory. Perform destructive repairs, upgrades, cache changes, and schema work on staging first.
What evidence should the report keep?
Keep exact versions, UTC timestamps, stable synthetic IDs, expected and actual results, the decision owner, rollback point, and final verification. Redact customer data, credentials, tokens, addresses, and private infrastructure details.
When is the task complete?
Complete the task when the primary user path passes, downstream records reconcile, failure branches are understood, monitoring is active, and an established owner page links to the new guide in context.
Mistakes to avoid
- Changing production before recording exact versions, UTC timestamps, stable fixture IDs, current settings, and a reproducible baseline.
- Treating one successful screen as proof that background jobs, APIs, caches, roles, reports, and downstream records agree.
- Deleting logs or identifiers before the failure boundary, business impact, rollback point, and accountable owner are known.
- Testing only an administrator session instead of the devices, roles, networks, data states, and failure paths real users have.
What to tell the client or owner
Give the site owner the affected versions, exact synthetic fixture, UTC timeline, before and after evidence, current cause class, decision, rollback point, unresolved risks, and next review date. State which measurements prove success and which observation window remains open.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, audit WooCommerce refund handling.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Recover checkout total conflicts before payment
For the purchase boundary, follow the WooCommerce 11.1 Store API expected_total conflict recovery to handle 409 repricing responses without duplicate orders, charges, inventory, or email.
Helpful references