WooCommerce 10.5 is introducing a significant shift in how WooCommerce product permalinks are generated. Specifically, it changes the logic used to select a category when a product is assigned to multiple terms. If you’ve ever pulled your hair out because a product URL chose a broad parent category instead of a specific sub-category, this update is for you. However, as with any change to URL structures, there are specific “gotchas” regarding SEO and legacy filters that you need to account for.
What’s Changing in WooCommerce 10.5?
Previously, WooCommerce selected the category for the permalink by sorting all assigned categories by their parent ID (descending) and then their term ID (ascending). While this worked, it was often inconsistent. It relied on database creation order rather than the semantic hierarchy of your store. Specifically, it could lead to URLs that didn’t reflect the most specific path to the product.
Starting with version 10.5, the logic now identifies the deepest category in the hierarchy. By counting the ancestors of each term, WooCommerce ensures that the most specific child category is prioritized. Furthermore, this change primarily affects stores using the “Shop base with category” structure or custom bases utilizing the %product_cat% placeholder.
The Logic: Old vs. New
In older versions, the code used wp_list_sort on the term array. This was a “naive” approach that often resulted in unpredictable permalinks if your categories weren’t created in a specific sequence.
// Legacy sorting logic (Pre-10.5)
$terms = wp_list_sort( $terms, array(
'parent' => 'DESC',
'term_id' => 'ASC',
) );
$category_object = $terms[0];The new approach iterates through the terms and calculates the depth of each using get_ancestors. Consequently, the term with the highest ancestor count becomes the canonical choice for the URL.
// New "Deepest Category" logic (10.5+)
$deepest_term = $terms[0];
foreach ( $terms as $term ) {
$ancestors = get_ancestors( $term->term_id, 'product_cat' );
if ( count( $ancestors ) > count( $deepest_ancestors ) ) {
$deepest_term = $term;
}
}Impact on SEO and WooCommerce Product Permalinks
Whenever URLs change, the first instinct is to worry about 404 errors and lost rankings. Fortunately, WooCommerce includes a built-in safety net. The wc_product_canonical_redirect() function handles 301 redirects from the old URL structure to the new one automatically. Therefore, while your WooCommerce product permalinks might look different in search results over time, your current traffic shouldn’t hit a wall.
However, if you have hard-coded links in your marketing emails or third-party integrations that don’t follow redirects, you might see a slight increase in server load as WordPress processes these 301s. It is always better to update those links where possible. For more on handling version transitions, check out my guide on the WooCommerce 10.5 variation price caching fix.
How to Restore Legacy Permalink Behavior
There are cases where you might want to keep the old behavior—perhaps a custom ERP integration or a specific SEO strategy requires the parent category to stay in the URL. You can easily revert this using the wc_product_post_type_link_product_cat filter. Specifically, this allows you to re-apply the legacy sorting logic before the permalink is generated.
/**
* Restore legacy WooCommerce product permalinks category selection.
*/
function bbioon_restore_legacy_permalink_logic( $category, $terms, $post ) {
if ( count( $terms ) <= 1 ) {
return $category;
}
$sorted_terms = wp_list_sort( $terms, array(
'parent' => 'DESC',
'term_id' => 'ASC',
) );
return $sorted_terms[0];
}
add_filter( 'wc_product_post_type_link_product_cat', 'bbioon_restore_legacy_permalink_logic', 10, 3 );Look, if this WooCommerce product permalinks stuff is eating up your dev hours or you’re worried about breaking your SEO, let me handle it. I’ve been wrestling with WordPress since the 4.x days and have seen every permalink disaster imaginable.
Takeaway for Store Owners
The move toward semantically “correct” URLs is a win for most stores. It makes your site hierarchy clearer to search engines and users alike. If you are preparing for the update, I recommend verifying your structure under Settings > Permalinks and checking the GitHub PR #62321 for the full technical breakdown. If you are already running WooCommerce 10.4, the jump to 10.5 should be smooth, provided you test your custom filters first.
