Magento 2 URL Rewrites

Share this article, Choose your platform!

Stop losing valuable organic traffic to “404 Page Not Found” errors and cryptic database links. This definitive guide breaks down how to master Magento 2 URL rewrites to create clean, high-ranking paths that search engines prioritise and customers trust.

What Are Magento 2 URL Rewrites?

In the competitive landscape of e-commerce, a URL is not merely a technical necessity—it is a critical Information Retrieval (IR) signal. By default, complex platforms like Magento 2 generate dynamic URLs based on database queries, which often look like catalog/product/view/id/123. While functional for a machine, these “ugly” URLs are detrimental to user experience and crawlability.

A URL Rewrite acts as a mapping layer between the server and the browser. It allows you to replace a technical path with a keyword-rich, human-readable string. To master this, you must understand the two components of every rewrite:

  • The Request Path: The “Front-facing” URL. This is what the user types into their browser and what Google indexes (e.g., brand-name-leather-boots.html).
  • The Target Path: The “Internal” URL. This is the actual route Magento uses to find the specific product, category, or CMS page in the database (e.g., catalog/product/view/id/45).

Why This Is a Non-Negotiable SEO Factor:

According to Backlinko, URLs are one of the top three ranking factors. Clean URLs provide “Topic Relevance” cues to search engines. Furthermore, research from MarketingSherpa indicates that descriptive URLs increase Click-Through Rate (CTR) by 24% because they reassure the user about the destination’s content.

How Magento 2 URL Rewrites Work: The Internal Mechanics

Magento 2 uses a systematic lookup process to handle every page request. This isn’t just a simple “switch”; it is a sophisticated database operation involving the url_rewrite table.

The url_rewrite Database Table

Every time a user requests a page, Magento performs a lookup in the url_rewrite table. This table stores the relationship between the friendly path and the system path. It includes columns for:

  • Store ID: Allowing different rewrites for different language views.
  • Is Autogenerated: Distinguishing between system-created links and manual marketing overrides.
  • Metadata: Information about the entity (product, category, or CMS page) being requested.

Rewrite vs. Redirect Logic

It is vital to distinguish between an internal rewrite and an HTTP redirect:

  1. Internal Rewrite: Magento matches the Request Path to the Target Path and serves the content without the URL in the browser bar changing. This is invisible to the user.
  2. HTTP Redirect (301/302): The server sends a response code to the browser. A 301 (Permanent) tells search engines that the old location is gone forever, passing 90-99% of “link equity” to the new URL. A 302 (Temporary) is used for short-term changes and does not pass ranking power.

Enabling and Configuring URL Rewrites

Before creating individual links, you must ensure the Magento core is set up to support “pretty” URLs. Without these settings, your server will default to including index.php in every link, which dilutes keyword density.

Step-by-Step Admin Configuration

  1. Log in to your Magento Admin Panel.
  2. Navigate to Stores > Settings > Configuration.
  3. In the sidebar, expand General and select Web.
  4. Open the Search Engine Optimization section.
  5. Set Use Web Server Rewrites to Yes. This tells Magento to use the server’s rewrite engine (Apache or Nginx) to hide the index.php part of the URL.
  6. Set Create Permanent Redirect for URLs if URL Key Changed to Yes. This is your safety net—if you rename a product, Magento will automatically point the old URL to the new one.

URL Suffix Settings

In the same configuration area, under Catalog > Catalog > Search Engine Optimization, you can define your Product URL Suffix and Category URL Suffix. While .html is traditional, many modern SEOs prefer to leave this blank for “cleaner” directory-style URLs. Changing this on an established site requires a full reindex and careful 301 mapping.

Creating URL Rewrites in Magento 2

Magento 2 provides three primary vectors for generating rewrites: automatic, manual, and bulk programmatic creation.

1. Automatic Generation (The Catalog Engine)

When you enter a “URL Key” on a product or category page, Magento’s indexers automatically populate the url_rewrite table.

  • The Workflow: You save a product named “Vintage Leather Bag.” Magento generates the key vintage-leather-bag. It then maps vintage-leather-bag.html to catalog/product/view/id/XX.
  • Category Path Integration: If you enable “Use Categories Path for Product URLs,” Magento will create longer paths like /accessories/bags/vintage-leather-bag.html. While this provides more context, it can lead to duplicate content if a product is in multiple categories. Always use Canonical Tags to mitigate this risk.

2. Manual Custom URL Rewrites (The Marketing Vector)

Marketing teams often need “vanity URLs” for print ads or social media.

  1. Navigate to Marketing > SEO & Search > URL Rewrites.
  2. Click Add URL Rewrite.
  3. From the Create URL Rewrite dropdown, select Custom.
  4. Request Path: Enter your desired vanity link (e.g., summer-sale).
  5. Target Path: Enter the internal Magento path or a specific product link.
  6. Redirect Type: Select Permanent (301) to ensure the ranking value of the short link is captured.

3. Redirect Matrix: Choosing Your Type

Redirect Type SEO Impact Best Use Case
No Rewrite Neutral Standard internal page mapping.
301 Permanent High (Link Equity) Renaming products, site migrations, deleting old pages.
302 Temporary Low Flash sales, maintenance pages, A/B testing.

Managing and Viewing the URL Rewrite Grid

As your catalog grows, the url_rewrite table can balloon to hundreds of thousands of rows. Efficient management is key to site performance.

Filters and Mass Actions

The grid at Marketing > SEO & Search > URL Rewrites allows you to filter by Store, Request Path, and Target Path.

  • Finding Conflicts: If a URL isn’t working, search the Request Path in this grid. Often, a duplicate entry is blocking the new one.
  • Exporting Data: For large-scale audits, use the Export tool to download your rewrites into a CSV. This allows you to identify “Redirect Loops” or “Chains” (e.g., URL A points to B, and B points to C) in Excel, which you can then fix to improve site speed.

Programmatic Creation of URL Rewrites

For developers migrating a site from Shopify or BigCommerce to Magento, manual entry is not feasible. You must use the Magento API or Service Contracts.

Using the UrlRewriteFactory

The following logic demonstrates how to create a rewrite within a custom module or migration script:

PHP

use Magento\UrlRewrite\Service\V1\Data\UrlRewrite;

use Magento\UrlRewrite\Model\UrlRewriteFactory;

 

// … inside your class …

public function createCustomRewrite($storeId, $targetPath, $requestPath) {

    $rewriteModel = $this->urlRewriteFactory->create();

    $rewriteModel->setStoreId($storeId)

        ->setTargetPath($targetPath)

        ->setRequestPath($requestPath)

        ->setRedirectType(301)

        ->setDescription(‘Legacy Migration Redirect’)

        ->setIsAutogenerated(0); // 0 = Manual/Custom

    

    try {

        $this->urlRewriteResource->save($rewriteModel);

    } catch (\Exception $e) {

        // Handle potential duplicate URL key exceptions

    }

}

 

Troubleshooting Common Rewrite Issues

When URL rewrites fail, it usually results in a 404 error, which can devastate your conversion rate. According to the Baymard Institute, broken links contribute significantly to the 73% cart abandonment rate.

1. The Reindex Requirement

Magento uses an indexer to keep the url_rewrite table updated. If you’ve imported products and links aren’t working, run:

bin/magento indexer:reindex catalog_url_rewrite

2. Cache Invalidation

Even after a reindex, the old URL might be cached in the browser or the server’s FPC (Full Page Cache).

bin/magento cache:flush

3. Server Configuration Conflicts

  • Apache: Ensure AllowOverride All is set in your virtual host and that the .htaccess file is present in the root.
  • Nginx: Check your nginx.conf. It must contain the specific rewrite directives for Magento 2. Magento provides a sample nginx.conf.sample file that includes these rules—ensure your configuration mirrors this.

4. Duplicate URL Keys

If two products have the same name, Magento may append a suffix (e.g., product-name-1). If this fails, the rewrite won’t be created. You must manually resolve these conflicts in the URL Rewrite grid.

Best Practices for SEO and Performance

To ensure your URL strategy drives revenue, follow these IR-engineered best practices:

  • Keep it Short: Users are more likely to remember and trust short URLs.
  • Avoid “Chains”: Every redirect adds milliseconds to page load time. Portent research shows that sites loading in 1s convert 3x better than those taking 5s.
  • Lowercase Only: While servers can be case-sensitive, users are not. Stick to lowercase to prevent 404s.
  • Hyphens over Underscores: Google treats hyphens as word separators, but it sees underscores as part of the word. Use blue-shoes, not blue_shoes.

Tools & Extensions for Advanced Management

If you are managing an Enterprise-level store, the default Magento tools may be insufficient.

  • Regenerate URL Rewrites (OlegKoval): An essential free tool for regenerating the entire rewrite table if it becomes corrupted.
  • Mirasvit Advanced SEO Suite: Automates redirect rules and identifies 404 errors in real-time.
  • Amasty SEO Toolkit: Provides a dashboard for managing meta-tags and rewrites in bulk, significantly reducing administrative overhead.

FAQs

How do I change the Base URL in Magento 2?

This is different from a URL rewrite. Navigate to Stores > Configuration > Web > Base URLs. Note that this changes the entire domain structure and should be done with extreme caution.

What is the difference between a 301 and 302 redirect?

A 301 is permanent and passes SEO value. A 302 is temporary and should only be used for short-term testing or seasonal promotions.

How do I remove index.php from my URLs?

Set Use Web Server Rewrites to Yes in the Admin panel and ensure your Apache/Nginx configuration is properly set up to handle the rewrite rules.

Why does Magento 2 strip GET parameters from URLs?

For security and to prevent duplicate content, Magento’s core logic often strips parameters like ?utm_source unless they are specifically allowed or handled via Javascript.