Creating URL Redirects When Updating Product URL Keys via the Magento API

If you’ve ever updated a product’s URL key via the Magento 2 REST API and then wondered why the old URL is now returning a 404, you’ve probably missed the url_key_create_redirect custom attribute.

In the admin UI there’s a handy “Create Permanent Redirect for old URL” checkbox that appears when you change a product’s URL key. Behind the scenes, this sets url_key_create_redirect on the product - and you can pass exactly the same attribute in your API requests to get the same behaviour.

¶The API request

When updating a product’s URL key, include url_key_create_redirect alongside url_key in your custom_attributes array:

PUT /rest/V1/products/{sku}

{
  "product": {
    "custom_attributes": [
      {
        "attribute_code": "url_key",
        "value": "new-product-url-key"
      },
      {
        "attribute_code": "url_key_create_redirect",
        "value": "1"
      }
    ]
  }
}

Setting the value to 1 tells Magento to create a 301 redirect from the old URL to the new one. The redirect is written to the url_rewrite table with redirect_type set to 301.

If you want to suppress redirect creation entirely - for example during a bulk initial import where no old URLs exist yet - set the value to 0 or omit the attribute.

¶Why this matters for bulk operations

If you’re running a bulk URL key update across hundreds or thousands of products, you’ll want to be deliberate about this. Passing url_key_create_redirect: 1 on every product creates a redirect entry for each one, which can pile up in url_rewrite over time - especially if products have had multiple URL key changes.

It’s worth cleaning out stale redirects periodically, or being selective about which updates warrant a redirect versus which are clean-slate changes (new products, dev/staging refreshes, etc.).

¶Verifying the redirect was created

You can check the url_rewrite table directly after the API call:

SELECT *
FROM url_rewrite
WHERE entity_type = 'product'
  AND redirect_type = 301
  AND target_path LIKE '%new-product-url-key%'
ORDER BY url_rewrite_id DESC
LIMIT 10;

Or use the REST API to inspect the product’s URL rewrites:

GET /rest/V1/url-rewrites/products/{product_id}

With a bit of luck this saves you the debugging time of wondering why your URL key updates are silently dropping old links.