> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Introduction

## Article: Introduction

## Article Link: https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/introduction.md

## Article Content:

# 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.

<blockquote class="important">

__Important:__
Changing or deleting a URL mapping on a published site changes the URLs of its item pages right away, and the old URLs stop working. The URL Mapping API doesn't create redirects. To keep old links and search rankings working, create 301 redirects from the old URLs to the new ones with [Bulk Create Redirects](https://dev.wix.com/docs/api-reference/business-management/seo/redirects/redirect-v1/bulk-create-redirects.md) in the SEO Redirects API.

</blockquote>

## 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](#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](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/get-url-mapping.md) 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](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/create-url-mapping.md), [Update URL Mapping](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/update-url-mapping.md), and [Delete URL Mapping](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/delete-url-mapping.md) 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](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/update-url-mapping.md), not [Create URL Mapping](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/create-url-mapping.md). 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](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/build-customized-url.md) 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](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/sample-flows.md#migrate-a-store-and-keep-its-product-urls)
- [Change a URL pattern on a published site](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/sample-flows.md#change-a-url-pattern-on-a-published-site)
- [Export item page URLs](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/sample-flows.md#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.

@sdk_package_setup