When WooCommerce 11.3 rejects a refund request with HTTP 400 or 422, inspect the error code and line allocations before retrying. An explicit refund line can exceed its remaining refundable balance even when the whole order has enough value left. Repeating the same invalid payload will not repair that mismatch.
This guide covers the 11.3 beta available on October 27, 2026. Rehearse on an isolated store with a test gateway and artificial orders. Do not experiment by issuing refunds against real customers.
Preserve the rejected request without its secrets
Record the order ID, timestamp, WooCommerce build, response status and woocommerce_rest_* error code. Retain the requested top-level amount, line-item IDs, line refund totals and tax allocations. Remove authorization credentials and personal information from the copy sent to a developer.
Separate an explicit validation response from a network timeout. A timeout leaves uncertainty about whether an operation completed and needs refund reconciliation. A validation failure explains why the submitted values were rejected. Neither should trigger an unconditional retry loop.
The upstream refund validation change tightens explicit line amounts. The release does not mean every 400 or 422 is this specific defect; use the returned code and details to identify the failed check.
Use order-line IDs, not product IDs
Retrieve the relevant order through the authorized integration and identify the actual order line. A product can appear in many orders, and a product ID is not a substitute for that order's line-item ID. Also check whether the allocation refers to a product, fee or shipping line.
Then list prior refunds for that order. Compare each target line's original value with the amount already refunded against that line. Do not infer the remaining line balance from the order total or payment-provider dashboard alone.
For example, use a synthetic two-line order with an original value of 60 on each line. If line A has already been refunded 45, it has 15 remaining. A new allocation of 20 to A is too large even though line B still has 60. Moving the extra 5 to B merely to pass validation is also wrong unless the authorized business refund actually concerns B.
Synthetic refund worksheet: compare each line with its remaining refundable balance, then compare allocated totals with the requested refund amount.
Reconcile the total and tax components
Compare the sum of the requested line allocations, including tax, with the top-level refund amount. Work in the order's currency and precision. Avoid mixing tax-inclusive displayed amounts with tax-exclusive line values.
| Check |
What can go wrong |
What to correct |
| Line ownership |
ID came from another order |
Map to this order's real line |
| Remaining amount |
Earlier partial refund was ignored |
Recalculate the remaining line balance |
| Overall allocation |
Line sum is larger than the requested refund |
Correct the approved allocation and total |
| Tax |
Tax is added twice or omitted |
Reconcile each tax component with the order |
| Sign |
A discount fee is treated like a positive product |
Preserve the line's accounting meaning |
Do not strip tax fields or change signs just to obtain a successful response. Ask the integration maintainer to explain the amount calculation and verify it against the order record. For preview-specific checks, use the refund calculation and tax parity guide.
Test rejection and success separately
In the isolated fixture, first demonstrate that an invalid allocation receives the expected rejection and does not add a refund record. Next submit a correctly approved test allocation once and inspect the resulting record. Finally, attempt a controlled over-allocation against the remaining line balance and confirm it is rejected.
Do not assume api_refund=false makes a request read-only. It can still create an order refund record even when it does not ask the payment gateway to transfer money. Use disposable test orders and an explicit recovery plan for the test environment.
For production operations, a saved WooCommerce refund and money reaching the customer are separate observations. Confirm the gateway result through the normal authorized workflow before telling the customer the transfer is complete. Keep automated customer notifications from claiming success solely because the request was sent.
Change the integration, not the validation
Remove automatic retries for unchanged validation failures. Show a useful operator message with the affected line and a redacted error, then require the allocation to be reviewed. Retain the previous integration version for recovery, but do not disable core validation to preserve inconsistent records.
Check the current release advisory again before deploying 11.3. For help tracing ERP, gateway and order-line mappings, request a focused WooCommerce repair with the synthetic reproduction and expected totals.
Sources checked October 27, 2026. Procedures and synthetic diagrams are explanatory, not claims of customer testing.
Refund API validation does not tell shoppers what the store promises. Separately verify the customer-facing policy link: WooCommerce 11.3 Return Policy Page: Verify the Link and Structured Data.