WooCommerce 11.1 adds a REST API refund calculation endpoint before the planned September 1 stable release. Extensions can use the calculation to preview refund amounts, but a correct item subtotal alone does not prove parity. Shipping, discounts, tax inclusion, compound tax, rounding, fees, partial quantities, currency precision, HPOS, and the final refund mutation can still diverge. The release gate compares the browser or admin expectation, calculation response, posted refund, order notes, stock action, payment gateway, and customer communication.
Use this for extension developers, stores, agencies, and finance teams testing WooCommerce 11.1 refund workflows before production rollout.
Quick answer
Create a fixture set covering tax-exclusive and tax-inclusive products, shipping tax, coupons, fees, partial quantities, mixed rates, and rounding edges. Call the calculation endpoint without posting a real refund, store the response, compare it with admin and independent order-line math, then create one authorized test refund. Reconcile the posted refund record, order totals, tax lines, gateway result, stock choice, email, and accounting export. Run the same fixtures with HPOS enabled and under the store's actual currency precision.
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 |
|---|
| Inclusive tax | Partial item refund | Tax and gross agree |
| Shipping | Partial shipping refund | Shipping tax agrees |
| Coupon and fee | Mixed adjustment | Rounding agrees |
| Posted refund | Gateway and order | Calculation matches mutation |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Freeze the release and tax configuration | Record the exact WooCommerce build, beta or stable phase, HPOS state, currency decimals, tax settings, prices-including-tax setting, and gateway behavior. | Calculation output matches independent line, tax, shipping, coupon, fee, and rounding expectations. |
| Build deterministic refund fixtures | Build deterministic orders with products, partial quantities, shipping, coupons, fees, mixed tax classes, inclusive and exclusive prices, and rounding boundaries. | The posted refund and gateway result match the approved calculation. |
| Compare every calculated line | Capture original order lines, requested refund lines, calculation response, admin preview, independent expected math, and every tax component. | HPOS and required currency and tax modes pass the same fixtures. |
| Post and reconcile one test refund | Post one authorized test refund and reconcile order totals, refund object, notes, stock action, gateway response, email, webhook, ERP, and accounting output. | The final 11.1 build is retested before production rollout. |
What to check first
- Record the exact WooCommerce build, beta or stable phase, HPOS state, currency decimals, tax settings, prices-including-tax setting, and gateway behavior.
- Build deterministic orders with products, partial quantities, shipping, coupons, fees, mixed tax classes, inclusive and exclusive prices, and rounding boundaries.
- Capture original order lines, requested refund lines, calculation response, admin preview, independent expected math, and every tax component.
- Post one authorized test refund and reconcile order totals, refund object, notes, stock action, gateway response, email, webhook, ERP, and accounting output.
- Repeat after the final 11.1 build and compare beta-to-stable deltas before production approval.
Field notes
- Write the expected result before changing anything and keep one repeatable canary fixture for the full test window.
- Record exact versions and UTC timestamps because caches, retries, scheduled actions, and deployments can change the evidence between checks.
- Test the public browser path and the stored server-side result, not only an admin preview or isolated API response.
- Close the task only after the visible workflow, logs, stored record, and relevant downstream system agree.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
order_id=WC-111-REF-04
prices_include_tax=yes
item_refund=42.00
shipping_refund=6.00
tax_refund=3.96
calculated_total=51.96
posted_total=51.96
gateway_total=51.96
parity=pass
Why this usually happens
- The integration compares only item subtotal and omits shipping, fee, discount, or tax lines.
- The store and extension round at different stages or currency precision.
- A calculation response is treated as proof that the later refund mutation and gateway result will match.
- Beta behavior is approved once and never repeated on the final 11.1 package.
Decision rule
Approve the endpoint only when calculated, admin, posted, gateway, tax, stock, email, and accounting evidence agree for every required fixture.
Production verification checklist
- Calculation output matches independent line, tax, shipping, coupon, fee, and rounding expectations.
- The posted refund and gateway result match the approved calculation.
- HPOS and required currency and tax modes pass the same fixtures.
- The final 11.1 build is retested before production rollout.
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 the release and tax configuration
- Build deterministic refund fixtures
- Compare every calculated line
- Post and reconcile one test refund
- Repeat on the final 11.1 build
Mistakes to avoid
- Changing production configuration before recording the exact version, failing request, timestamp, and rollback point.
- Treating a clean dashboard or one successful request as proof while the public page, background job, log, stored record, and downstream system remain unchecked.
- Testing a different role, device, locale, order state, form, cache state, or integration path from the one that users actually reach.
- Leaving debug logging, temporary exclusions, duplicate hooks, helper code, test endpoints, or broad permissions active after the verification window.
Questions teams ask during testing
Can I make this change directly in production?
Start with read-only evidence and use staging for code, update, security, checkout, form, or queue changes. If production is required, use one named canary, a short monitored window, and a tested rollback.
How do I avoid a false positive?
Repeat the same fixture with the same versions, role, URL, device, locale, cache state, and downstream integration. Compare stored evidence rather than relying on a visual impression.
What evidence should I retain?
Keep UTC time, exact versions, URL or record ID, expected and actual result, relevant log lines, change made, rollback point, owner, and final verification. Redact credentials and personal data.
When should I escalate?
Escalate when the site is unavailable, security scope is unclear, checkout or lead capture is affected, several systems disagree, or the next action could destroy evidence.
What to tell the client or owner
Give the owner a concise evidence packet with the affected workflow, exact versions, UTC test time, fixture ID, expected result, actual result, key logs, change made, rollback point, final result, owner, and next review date. Remove credentials and personal data before sharing it.
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, have HandL WP test the WooCommerce 11.1 refund workflow.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references