Field guide · technical workflow
Test Adobe Commerce URL rewrites before they surprise you
URL rewrites are easy to approve as an administrative setting and harder to assess across thousands of commercial URLs. A category edit can have consequences far outside the page being changed. This article turns the issue into a sample-based QA process with explicit ownership, redirect checks and rollback decisions.
Who this is for: Give an Adobe Commerce technical lead a release-ready way to audit rewrite behaviour across products, categories and multiple store views.
Editorial preview — facts, worked examples and publication approval are still being checked.
The practical problem
A release matrix records the URL class, store view, original destination, new route, redirect response, canonical target and developer decision. The included rows are deliberately synthetic, allowing teams to run a controlled QA rehearsal without mistaking examples for site-specific findings.
What you will be able to check
- Export representative current product, category and CMS URLs in each relevant store view.
- Record the expected rewrite destination and distinguish intentional redirects from accidental chains.
- Test actual HTTP responses, final canonical tags, navigation paths and category/product exceptions.
- Keep a rollback owner and post-deployment checks for affected high-value templates.
Reproducible scenario
A category rename that also touches product paths
Imagine a PaaS Adobe Commerce installation with two store views, a 'Desk accessories' category and several products linked under that category. A merchandising editor proposes changing the category URL key before a seasonal release. The risk is not that the new category fails to display: it is that legacy category URLs, product-category rewrites and store-view links may now disagree. Adobe documents the URL Rewrite admin interface for PaaS/on-premises; Cloud Service and headless storefront routing need a different technical review. All paths here are synthetic.
Starting assumptions
- The store has a default English view and a second locale with distinct routes; both must retain direct navigation to their products.
- The team can export existing URL rewrite rules and run a staging crawl before scheduling the change in its deployment window.
Decisions and checks
Record the current category and product routes from both store views
The technical lead samples the category URL, two products and one CMS page in each view and logs the actual request path, response, canonical and breadcrumb. The category's current URL key and any existing rewrite rules become baseline evidence. This avoids assuming the default view's behaviour applies across every language or market.
What to verify: A before-state matrix with separate rows for each store view, source URL and expected canonical owner, including actual existing redirect chains.
Agree the intended old-to-new rewrite behaviour before approving the change
The change specification explains whether each old category route should permanently redirect to its equivalent new route and whether product addresses remain canonical. Adobe distinguishes an internal URL rewrite from an external HTTP redirect, so the engineer must verify actual response codes rather than assuming any routing rule returns a 301.
What to verify: A signed mapping table that states the HTTP result, final destination, product relevance and specific exceptions for each affected route class.
Rehearse cutover on a representative large-category and secondary-view sample
Adobe warns that generating product and category rewrites while saving a category can have performance implications for categories with many products. The release owner records the expected rewrite workload, tests the affected routes and sets a rollback strategy without claiming a performance threshold that was never measured.
What to verify: A staging trace of the selected rewrite operations, direct URL requests and destination HTML in both views, with a clear go/no-go decision.
Expected output: The useful output is a bounded URL rewrite acceptance contract, not a claim that the new URL key has already been deployed safely. It identifies the PaaS store views and representative URL classes, records the old and new paths, and makes developers accountable for final response and canonical parity. The review can then distinguish real failures from an administrative preference for shorter URL keys, and only a verified production retest closes the change.
The category names, number of store views and URL examples are hypothetical. This is a technical planning scenario, not a claim of an Adobe Commerce audit or measured client outcome.
The change that travels further than expected
An editor improves a category URL key and clicks save. The visible category looks better, but any automatically generated product-path rewrites, linked navigation and store-view variants still need inspection. The starting question is not whether redirects are enabled; it is which existing URLs the change can touch and how those URLs are currently reached.
Adobe's URL rewrite documentation describes permanent redirects for changed product, category and CMS-page URLs in Adobe Commerce PaaS and on-premises installations. The referenced administrative workflow is not a verified description of Adobe Commerce as a Cloud Service; that storefront implementation needs its own platform-specific checks. Treat the documented defaults as behaviour to verify on the actual installation, not as a promise for every Commerce deployment.
Reference: official · 2026-11-07official · 2026-11-07
Sample the routes that matter
Take a stratified set of URLs: high-value category, parent and child category, active product, discontinued product, store-view alternate and CMS page. For each, record the request path, response code, final destination, canonical and internal links. A redirect that works for one route does not show how a different store-view or product relationship behaves.
Include both browser testing and an HTTP-level crawl. Watch for long redirect chains, changed parameters, broken category navigation and canonicals pointing to a different store view. If a revised URL is deliberately retired, record the reason and the correct response rather than redirecting every missing product to the home page.
Reference: official · 2026-11-07official · 2026-11-07
Give developers an acceptance contract
A useful handover lists actual sample paths and precise expected outcomes: permanent redirect to the matching successor, canonical in the final HTML, retained internal navigation and a healthy sitemap. Attach a list of known exceptions and ask the implementation owner to record before-and-after receipts.
Use the accompanying CSV as a release matrix rather than a cosmetic checklist. Once the change is deployed, run the same rows against production and compare the result with the approved baseline. If the store has different locales, make the evidence store-view-specific; do not approve a global change from a single default-store test.
Reference: official · 2026-11-07official · 2026-11-07
Decision aid
URL rewrite decisions a release owner can actually test
| Illustrative route or state | Expected action | Acceptance evidence |
|---|---|---|
| An old category URL renamed for the same collection | Usually a relevant permanent redirect if the old path is replaced and the new page serves the same category. | Record the old request, Location response, final product list and new self-canonical. |
| A product linked through two old category contexts | Preserve or consolidate paths according to the site's chosen canonical product strategy. | Compare HTTP chains, product identity and internal category-product links in both store views. |
| A non-default store-view page after a category URL key change | Review against that view's actual localized equivalent, not an English default destination. | Test local path, final language and canonical/hreflang signals on rendered HTML. |
| An Adobe Commerce as a Cloud Service storefront | Do not apply PaaS admin instructions as if the Cloud Service routing stack were identical. | Refer to the deployment's own storefront routing documentation and inspect its actual edge or app configuration. |
What a passing test looks like
These checks describe the evidence that should exist after a real implementation. They are not reports of tests already completed on a customer website.
Export the baseline URL rewrite inventory for each configured store view
Expected result: The record identifies what exists before the category edit and which source paths still receive navigation or traffic.
Keep as evidence: Attach an admin export or sanitized route list and a representative HTTP crawl.
Test the category rename against real products and legacy category links
Expected result: Every selected old URL reaches a relevant successor without unexpected loops or an unrelated product/category.
Keep as evidence: Capture request headers, final URLs and screenshots showing the product assortment before and after.
Check canonical, sitemap and internal-link parity on the destination pages
Expected result: The new preferred URLs are consistent across HTML, navigation and the sitemap after deployment.
Keep as evidence: Store the sitemap diff, canonical extraction and resolved link checks from both store views.
Confirm performance and rollback risks for rewrite generation
Expected result: The release owner knows what will be generated, how long it took in the tested environment, and which rule can safely be reverted.
Keep as evidence: Save the staging execution notes, rollback owner and release go/no-go approval.
Questions worth resolving
Is a URL rewrite always the same thing as an HTTP 301 redirect?
No. Adobe's documentation distinguishes an internal server-side rewrite, which may leave the browser's displayed address unchanged, from a redirect response that instructs the browser to move to another URL. The PaaS URL Rewrite admin tool can create permanent redirects for changed URL keys, but a developer must request the source URL and record the observed status and destination rather than treating a configuration label as verification.
Can the same instructions be used on Adobe Commerce as a Cloud Service?
Not without a deployment-specific review. Adobe's current SEO overview labels some URL rewrite, metadata and sitemap instructions as PaaS only and points Cloud Service users to Commerce Storefront guidance. A headless or edge-delivered shop can have a different routing and canonical mechanism. Identify the actual Commerce edition and storefront before promising that a back-office rewrite checkbox controls live behaviour.
Scope and limitations
This walkthrough describes an illustrative Adobe Commerce PaaS/on-premises release. It does not establish the real rewrite table, the number of products affected, custom extensions, locale configuration or performance of any client installation. Cloud Service routing must be investigated separately. A successful staging run also does not prove that production caches, edge rules and live links behave identically. Require production HTTP and HTML checks and preserve rollback procedures before presenting the migration as accepted.
Sources and verification
These references explain documented technical behaviour. The worked decisions are illustrative until checked on your own installation.
- official reference — The official Adobe guide describes URL rewrite behaviour for PaaS/on-premises Commerce and explicitly directs Cloud Service installations to a different storefront SEO guide. Recorded: 2026-11-07
- official reference — This official technical reference is used as a supplementary source for canonical, crawl, commerce or SEO implementation decisions discussed in the guide. Recorded: 2026-11-07