About the URL Mapping API

A URL mapping sets the URL pattern for one type of item page on a site, such as all Stores product pages or all Blog post pages. For example, the pattern shoes/{{slug}} gives a product with the slug red-shoes the URL /shoes/red-shoes.

With the URL Mapping API, you can:

• Retrieve the URL patterns that a site uses for its item pages.
• Set, change, or remove the URL pattern for a type of item page.
• Build the URLs of specific items from a site's URL pattern.

Supported item pages

A site has at most one URL mapping per key. Each key stands for one type of item page and sets the variables its pattern must use:

Key	Page type	Variables	Default URL
wix.stores.sub_pages.product	Stores product page	slug	<prefix>/{{slug}}
wix.blog.sub_pages.post	Blog post page	slug	<prefix>/{{slug}}
wix.blog.sub_pages.category	Blog category page	slug	<prefix>/categories/{{slug}}
wix.bookings.sub_pages.service_page	Bookings service page	slug	<prefix>/service-page/{{slug}}
wix.online_programs.sub_pages.online_program	Online Programs program page	slug	<prefix>/challenge-page/{{slug}}
wix.forum.sub_pages.category	Forum category page	slug	<prefix>/{{slug}}
wix.forum.sub_pages.post	Forum post page	categorySlug, postSlug	<prefix>/{{categorySlug}}/{{postSlug}}
wix.groups.sub_pages.group	Groups group page	groupId, tabName	<prefix>/{{groupId}}/{{tabName}}

Default URLs

When a site has no URL mapping for a key, its item pages use the default URL for that key, shown in the Supported item pages table. <prefix> is the URL of the page that shows the items. For example, when a store's product page has the URL product-page, its products default to product-page/{{slug}}. When the page's URL already matches a fixed segment, such as service-page, the segment isn't repeated.

In this case, Get URL Mapping returns an empty response rather than an error. Deleting a URL mapping returns the item pages to their default URL.

Before you begin

It's important to note the following points before starting to code:

• Create URL Mapping, Update URL Mapping, and Delete URL Mapping change the site's live URLs as soon as they succeed, with no site publish.
• To change an existing URL mapping, call Update URL Mapping, not Create URL Mapping. Update URL Mapping replaces the whole URL mapping for the key.
• The business solution doesn't need to be installed on the site to create its URL mapping. The pattern applies to the item pages once it's installed.
• Build Customized URL only builds URLs for a key that has a URL mapping on the site. It inserts variable values as is, without URL encoding, so send URL-safe values.

Use cases

• Migrate a store and keep its product URLs
• Change a URL pattern on a published site
• Export item page URLs

Terminology

• URL mapping: The URL pattern that one type of item page on a site uses, identified by its key.
• Key: The type of item page that a URL mapping applies to, such as wix.stores.sub_pages.product.
• Pattern: The mapping value. A path relative to the site's base URL, with variables in double curly braces, such as shoes/{{slug}}.
• Variable: A placeholder in a pattern that's replaced with an item's value, such as slug.
• Default URL: The URL an item page uses when the site has no URL mapping for its key.