The official WooCommerce 11.3 release came out on November 11, 2026. The On-Sale Badge block can now show the amount or percentage a shopper saves. Product and catalog blocks get more styling controls, and Product Gallery swipes feel smoother on mobile. Stores can set a refund and returns policy page. The REST API now rejects refunds with bad line-item amounts.
Most of 11.3 is small fixes. But a few of them touch refunds and failed payments. If you sell with deposits or installments, those are the ones to look at closely.
Black Friday is on November 27, so there isn’t much time to test. Below is what changed and what to check on staging before you update.
WooCommerce 11.3 Release Date and Feature Summary
WooCommerce 11.3.0 was released on November 11, 2026. The release notes mark it as backwards compatible. It also runs a database update, so take a backup before you click Update.
Here is a quick view of the changes store owners will notice.
| Change | What it does | Who it affects |
| On-Sale Badge options | Shows the amount or percent saved, or your own text | Stores running sales |
| Block styling controls | More design settings on product and catalog blocks | Block theme stores |
| Product Gallery swipes | Native scrolling with scroll snap on phones | Mobile shoppers |
| Refund and returns policy page | Pick a policy page and Woo adds structured data for it | All stores |
| Refund API checks | Rejects refunds with bad line-item amounts | Tools that refund by API |
| Analytics payment method | Shows the gateway in the Orders report | Store owners, large stores |
| MCP endpoint removed | Old AI tool connection is gone | Stores linked to AI tools |
What Does the On-Sale Badge Block Do in WooCommerce 11.3?
Until now the badge said โSaleโ and nothing else. In 11.3 it can show the amount saved, like โ$5.00โ, or the percentage, like โ25%โ. You can also swap โSaleโ for your own words, such as โSpecial offerโ.
- To change it, select the badge in the Product Catalog or Single Product template.
- Open Badge content and pick an option under Show. Amount and percentage both take a prefix and a suffix.
- Add โSave โ before and โ offโ after, and the badge reads โSave 25% offโ.
Existing badges keep saying โSaleโ until you edit them.
On variable products, the badge shows the biggest discount with โUp toโ, like โUp to 50%โ. On a single product page it switches to the discount of the variation the shopper picks.
If that variation isn’t on sale, the badge hides.
For a Black Friday sale, that matters. Shoppers see the actual saving on the product card before they click. We covered more BFCM checkout ideas in our buy now pay later plugins for BFCM guide.
What New Styling Controls Do WooCommerce Blocks Get?
Several product blocks get new design settings in 11.3. The release notes name the Product, Featured Product, Featured Category and Product Categories List blocks. Catalog Sorting and the Product Results Count get them too.
Most blocks get color and spacing options. Some also get borders or typography settings, according to the changelog.
Featured Category now works inside the core Terms Query block. So you can build a grid of category cards with one shared design and no custom CSS.
Why do Product Gallery swipes feel different on mobile?
The Product Gallery block now uses the browser’s own scrolling with scroll snap. Images follow the shopper’s finger. A quick flick carries on to the next image with natural momentum.
Woo says it made the change based on user feedback.
How Do You Set a Refund and Returns Policy Page in WooCommerce 11.3?
Go to WooCommerce > Settings > Advanced > Page setup. Pick your refund and returns policy page and save.
WooCommerce then labels that page in your Pages list. It also adds structured data that links to it. Search engines and AI shopping agents can find your policy without custom markup.
If you take deposits, use this page to explain refunds in plain words.
- Say what happens to a deposit when an order is cancelled.
- Then say how you refund an order that is only partly paid.
Shoppers on a payment plan want that answer before they commit.
What Changed in the WooCommerce 11.3 Refund API?
The refunds endpoint now checks line-item amounts before it creates a refund. The endpoint is POST /wp-json/wc/v3/orders/{order_id}/refunds.
A request now fails if it breaks any of these rules:
- Each nonzero line amount must point to a line on the same order.
- A line’s refund total plus its refund tax can’t be more than what’s left to refund on that line.
- All line amounts together, tax included, can’t be more than the refund’s top-level amount.
- Each amount needs the right sign for its line. Negative refunds still work for negative lines, such as discount fees.
A bad request returns HTTP 400 or 422 with a woocommerce_rest_* error code. No refund gets created.
The developer notes give an example. Sending an amount of โ3โ with a line refund_total of 4 returns 400 woocommerce_rest_invalid_refund_amount.
Woo made this change because these requests used to go through. They left order records and Analytics reports out of sync.
If any tool or custom code refunds orders through the API, check how it handles these errors. Log the error and fix the amounts before you send a new request. Don’t treat a finished call as a finished refund.
We covered the new refund endpoint and its preview mode in our WooCommerce 11.1 release details.
Version 11.3 adds the checks on top.
Which Checkout and Payment Fixes are in WooCommerce 11.3?
The 11.3 changelog is long. These are the fixes that touch money at checkout.
Can a checkout retry still mark a cancelled order as paid?
No. 11.3 stops checkout retries from marking cancelled, unpaid orders as paid (PR #69265).
A related Store API fix covers the opposite case. Sometimes a failure happens after the gateway has already taken payment. Checkout now reports that order as successful.
So shoppers are no longer told to retry an order they already paid for.
What changed on the Pay for order page?
Merchants can create an order in the admin and send the customer a link to pay it. In 11.3, that Pay for order page pre-selects the payment method set on the order (PR #68751). Before, it picked the first enabled method.
The Store API also blocks one change on that page. A customer can’t edit the address if the edit would change the order’s shipping cost or tax (PR #70364).
Does a VAT-exempt customer keep the exemption after a failed payment?
Yes, from 11.3 on.
Before, checkout saved the customer account and the VAT exemption flag reset to false. So a VAT-exempt customer with a declined card got charged tax on the retry. Now the flag stays in the session (PR #69615).
What other payment fixes should you know about WooCommerce 11.3?
- Block checkout now pre-selects the customer’s default saved payment method.
- Saved payment methods without card details get clearer labels in Checkout and My Account.
- Payments settings show a โLimited compatibilityโ badge when an enabled gateway has no Checkout block integration.
- Direct bank transfer and Check payments get the โEnable for shipping methodsโ setting. They also get โAccept for virtual ordersโ, matching Cash on delivery.
- Failed Store API cart requests no longer copy cart data into pending orders.
For a wider look at checkout, see our WooCommerce checkout plugins guide compares the main options.
What Does the New Analytics Payment Method Filter Need From Your Database?
The Analytics Orders report now shows the payment method for each order. It appears as a column in the table and in CSV exports. There’s also a new advanced filter for it.
To make this work, 11.3 adds a payment_method column and an index to the wc_order_stats table. A background job fills in old orders through Action Scheduler, 500 orders per batch. Until it finishes, older orders show no payment method.
- On large stores, building the index takes time and disk work. The developer pre-release post puts the index at about 47 MB per million orders.
- On older database servers such as MySQL 5.7, the whole table gets rebuilt.
So run the update at a quiet hour, not on a sale day.
One note for developers. Custom Analytics SQL that joins wc_orders and uses a bare payment_method column will now fail as ambiguous. Add the table name to fix it.
Did WooCommerce 11.3 fix double-counted refunds in Analytics?
Yes. A new tool under WooCommerce > Status > Tools looks for refunds counted twice.
It finds orders where a partial refund and a later full refund both landed in the Revenue report’s returns, then re-imports them (PR #66505).
If you often refund in parts, run its check after you update.
What Happened to the WooCommerce MCP Endpoint in 11.3?
This part only matters if an AI tool talks to your store through WooCommerce’s own MCP endpoint. Most store owners can skip it.
WooCommerce 11.3 removes the old /wp-json/woocommerce/mcp endpoint and the REST API key connection that went with it. WooCommerce also stops bundling the MCP Adapter and Abilities API packages.
To reconnect, install the WordPress MCP Adapter plugin and log in with a WordPress application password.
What Should Developers Check Before Updating to WooCommerce 11.3 Release?
Most of these are edge cases. Still, each one can break custom code. The developer post has the full detail.
- Products REST and Store API: on_sale combined with include or exclude now returns only matching products. Before, on_sale=true&include=10,13 could return 10, 13, 15, 16, 17 and 18. Now it returns 13.
- Product Collection now uses the Product Filters engine for URL filters. Code that edits generated meta_query or tax_query clauses should change query arguments instead.
- With a block theme active, reading the Shop page’s _wp_page_template meta now returns archive-product.
- Store API cart items get a parent_item_key field, so bundle-style extensions can mark child items. Nothing breaks if you ignore it.
What Does WooCommerce 11.3 Mean for Payment Plans and Deposits?
WooCommerce 11.3 adds nothing aimed at payment plans. But several fixes touch orders that get paid in more than one step. Test these on a staging copy before you update the live store:
- Refund part of a partly paid order. If anything in your setup refunds through the REST API, send an amount above the remaining balance and check that it fails.
- Fail a payment on purpose, then retry it. Check the final order status. For a VAT-exempt customer, check that the retry isn’t taxed.
- Create an order in the admin and open its Pay for order link. Check which payment method is selected.
- Open WooCommerce > Settings > Payments and look for the โLimited compatibilityโ badge next to your gateways.
- After the background update finishes, filter the Analytics Orders report by payment method. Compare the totals with your gateway dashboard.
If a plugin runs your deposits or installments, ask its developer whether they’ve tested it on 11.3. And keep the customer side in mind too.
Our post on buy now pay later mistakes covers the problems merchants hit most often.
WooCommerce 11.3 Requirements and the PHP 8.1 Notice
WooCommerce 11.3 readme lists WordPress 7.0 as the minimum, tested up to 7.1. The minimum PHP version is 7.4.
Stores on PHP older than 8.1 now see an admin notice. It warns that older PHP versions may have critical security flaws and recommends PHP 8.3. The changelog says PHP 8.1 becomes the minimum in WooCommerce 11.6.
On PHP 7.4 or 8.0? Ask your host about 8.3 and test it on staging first.
With Black Friday this close, many stores will wait until December.
WooCommerce 11.3 Release Update Checklist
Use this list in order.
- Take a full backup of your files and database.
- Copy the store to staging and update WooCommerce there first.
- Let the database update finish. On a big store, watch Action Scheduler for the payment method backfill.
- Place a test order with a deposit or installment plan and pay it.
- Refund part of a partly paid order. Check the order and the Analytics totals.
- Fail a payment and retry it. Check the order status and the tax.
- Open a Pay for order link and check the selected payment method.
- Check Payments settings for a โLimited compatibilityโ badge.
- Set your refund and returns policy page under Settings > Advanced > Page setup.
- Update the live store at a quiet hour. Then hold off on other changes until after Black Friday.
Final Word on WooCommerce 11.3 Release
WooCommerce 11.3 is easy to plan for. It’s backwards compatible, but it runs a database update, so back up first. Shoppers will notice the sale badges first. For stores that take deposits or installments, the refund checks and retry fixes deserve an hour on staging.
If you want to give customers the option to pay over time, see the Payment Plans for WooCommerce features or check pricing.
