URL Mapping: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Migrate a store and keep its product URLs

A Wix user moves a store to Wix from a platform where product pages live at /products/<slug>. By default, the Wix site serves them under its product page's path prefix instead, such as /product-page/<slug>. Setting the Stores product pattern to match the old platform keeps every product's URL the same, so only products whose slug changed during the import need a redirect.

To migrate a store and keep its product URLs:

1. Call Create URL Mapping with key set to wix.stores.sub_pages.product, and a urlMapping whose mapping is products/{{slug}}. For example:

   Copy

2. Import the products, and list each product whose slug on Wix differs from its slug on the old platform, with both slugs.

3. Call Build Customized URL with the same key, and an itemsData entry with the Wix slug of each of those products. The response's urls are in the same order as itemsData, so pair each URL with its product's old path, such as /products/red-shoes-1.

4. Call Bulk Create Redirects in the SEO Redirects API with the pairs, as from and to, in batches of up to 100. Some redirects in a batch can fail while the rest succeed, so check results and bulkActionMetadata in each response and retry the failed ones.

Change a URL pattern on a published site

A Wix user set the Blog post pattern to blog/{{slug}} and now wants posts to move to articles/{{slug}}. The new URLs are live as soon as the pattern changes, and the old URLs stop working, so build the old URLs first and redirect them to the new ones.

To change a URL pattern on a published site:

1. Call Get URL Mapping with key set to wix.blog.sub_pages.post, and keep the urlMapping from the response.
2. Collect the slug of every post on the site, using List Posts in the Wix Blog API.
3. Call Build Customized URL with the same key and an itemsData entry with each post's slug, such as { "itemData": { "slug": "my-first-post" } }. Keep the returned urls as the old URLs. Send up to 10,000 items per request.
4. Call Update URL Mapping with the same key, passing the whole urlMapping you retrieved with mapping set to articles/{{slug}}.
5. Call Build Customized URL again with the same itemsData, in the same batches. The returned urls are the new URLs, in the same order as the old ones.
6. Call Bulk Create Redirects in the SEO Redirects API with each old URL as from and its new URL as to, in batches of up to 100. Some redirects in a batch can fail while the rest succeed, so check results and bulkActionMetadata in each response and retry the failed ones.

Export item page URLs

An app generates a product feed or an external sitemap and needs the full URL of every product page. Build Customized URL returns them in bulk from the site's pattern, so the app doesn't have to rebuild the pattern itself.

To export item page URLs:

1. Call Get URL Mapping with key set to wix.stores.sub_pages.product, and read variables from the response to learn which values each item needs.
2. Collect those values for every product, using Query Products in the Wix Stores Catalog API. Values are inserted as is, without URL encoding, so make sure each value is URL-safe.
3. Call Build Customized URL with the same key, an itemsData entry for each product, and options.baseUrl set to the site's URL, such as https://www.my-store.com/. Send up to 10,000 items per request.
4. Match the returned urls to your products by position, and add them to the feed or sitemap.