> 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 # CreateUrlMapping # Package: seo # Namespace: UrlMappingWriterService # Method link: https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/create-url-mapping.md ## Permission Scopes: Manage SEO Settings: SCOPE.PROMOTE.MANAGE-SEO ## Introduction Creates a URL mapping for one type of item page. A site can have one URL mapping per key. The business solution doesn't need to be installed on the site yet. The pattern applies to the item pages once it's installed. The change is live on the site right away. On a published site, the item pages' old URLs stop working, so create redirects from them with [Bulk Create Redirects](https://dev.wix.com/docs/api-reference/business-management/seo/redirects/redirect-v1/bulk-create-redirects.md). --- ## REST API ### Schema ``` Method: createUrlMapping Description: Creates a URL mapping for one type of item page. A site can have one URL mapping per key. The business solution doesn't need to be installed on the site yet. The pattern applies to the item pages once it's installed. The change is live on the site right away. On a published site, the item pages' old URLs stop working, so create redirects from them with [Bulk Create Redirects](https://dev.wix.com/docs/api-reference/business-management/seo/redirects/redirect-v1/bulk-create-redirects.md). URL: https://www.wixapis.com/url-mapper/writer/v1/url-mapping/{key} Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: urlMapping Method parameters: param name: urlMapping | type: UrlMapping | description: A custom URL pattern for one type of item page on a site, such as all Stores product pages. A site has at most one URL mapping per `key`. When a site has no URL mapping for a key, the item pages use the key's default URL, which depends on the key. For example, Stores product pages default to `/{{slug}}` and Blog category pages to `/categories/{{slug}}`. | required: true - name: key | type: string | description: Type of item page this URL mapping applies to, and the variables its `mapping` must use: + `wix.stores.sub_pages.product`: Stores product page. Variables: `slug`. + `wix.blog.sub_pages.post`: Blog post page. Variables: `slug`. + `wix.blog.sub_pages.category`: Blog category page. Variables: `slug`. + `wix.bookings.sub_pages.service_page`: Bookings service page. Variables: `slug`. + `wix.online_programs.sub_pages.online_program`: Online Programs program page. Variables: `slug`. + `wix.forum.sub_pages.category`: Forum category page. Variables: `slug`. + `wix.forum.sub_pages.post`: Forum post page. Variables: `categorySlug`, `postSlug`. + `wix.groups.sub_pages.group`: Groups group page. Variables: `groupId`, `tabName`. Other values aren't supported. - name: mapping | type: string | description: URL pattern for the item pages, relative to the site's base URL. Wrap variables in double curly braces, for example `shoes/{{slug}}`. The pattern must use every variable listed for its `key`, and no others. The pattern is saved in lowercase. Rules: up to 1,000 characters; no spaces, emoji, or URL-reserved characters; no leading or trailing slash; no empty segments; at most one variable per segment. The resulting URLs can't collide with another page on the site or with another URL mapping. Return type: CreateUrlMappingResponse - name: urlMapping | type: UrlMapping | description: Created URL mapping. - name: key | type: string | description: Type of item page this URL mapping applies to, and the variables its `mapping` must use: + `wix.stores.sub_pages.product`: Stores product page. Variables: `slug`. + `wix.blog.sub_pages.post`: Blog post page. Variables: `slug`. + `wix.blog.sub_pages.category`: Blog category page. Variables: `slug`. + `wix.bookings.sub_pages.service_page`: Bookings service page. Variables: `slug`. + `wix.online_programs.sub_pages.online_program`: Online Programs program page. Variables: `slug`. + `wix.forum.sub_pages.category`: Forum category page. Variables: `slug`. + `wix.forum.sub_pages.post`: Forum post page. Variables: `categorySlug`, `postSlug`. + `wix.groups.sub_pages.group`: Groups group page. Variables: `groupId`, `tabName`. Other values aren't supported. - name: mapping | type: string | description: URL pattern for the item pages, relative to the site's base URL. Wrap variables in double curly braces, for example `shoes/{{slug}}`. The pattern must use every variable listed for its `key`, and no others. The pattern is saved in lowercase. Rules: up to 1,000 characters; no spaces, emoji, or URL-reserved characters; no leading or trailing slash; no empty segments; at most one variable per segment. The resulting URLs can't collide with another page on the site or with another URL mapping. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: | Description: The `key` isn't supported, doesn't match `urlMapping.key`, or a required field is missing. Details are in `fieldViolations`. HTTP Code: 409 | Status Code: ALREADY_EXISTS | Application Code: URL_MAPPER_SAVE_CONFLICT | Description: Another write to the site's URL mappings happened at the same time. Nothing is saved. Retry. HTTP Code: 409 | Status Code: ALREADY_EXISTS | Application Code: URL_MAPPER_ALREADY_EXISTS | Description: There is already a URL mapping with this `key`. To change it, call [Update URL Mapping](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/update-url-mapping.md). HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: | Description: The `mapping` pattern breaks a pattern rule (see `mapping`), for example it's missing a required variable, uses an unknown one, or collides with another page. Details are in `fieldViolations`. ``` ### Examples ### Create a URL mapping for Stores product pages Sets the URL pattern for all product pages on the site, so a product with the slug `red-shoes` gets the URL `/shoes/red-shoes`. ```curl curl -X POST \ 'https://www.wixapis.com/url-mapper/writer/v1/url-mapping/wix.stores.sub_pages.product' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "urlMapping": { "key": "wix.stores.sub_pages.product", "mapping": "shoes/{{slug}}" } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.seo.urlMappings.createUrlMapping(key, urlMapping) Description: Creates a URL mapping for one type of item page. A site can have one URL mapping per key. The business solution doesn't need to be installed on the site yet. The pattern applies to the item pages once it's installed. The change is live on the site right away. On a published site, the item pages' old URLs stop working, so create redirects from them with [Bulk Create Redirects](https://dev.wix.com/docs/api-reference/business-management/seo/redirects/redirect-v1/bulk-create-redirects.md). # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: key, urlMapping Method parameters: param name: key | type: string | description: Type of item page to create the URL mapping for. Must match `urlMapping.key`. | required: true param name: urlMapping | type: UrlMapping | description: A custom URL pattern for one type of item page on a site, such as all Stores product pages. A site has at most one URL mapping per `key`. When a site has no URL mapping for a key, the item pages use the key's default URL, which depends on the key. For example, Stores product pages default to `/{{slug}}` and Blog category pages to `/categories/{{slug}}`. | required: true - name: key | type: string | description: Type of item page this URL mapping applies to, and the variables its `mapping` must use: + `wix.stores.sub_pages.product`: Stores product page. Variables: `slug`. + `wix.blog.sub_pages.post`: Blog post page. Variables: `slug`. + `wix.blog.sub_pages.category`: Blog category page. Variables: `slug`. + `wix.bookings.sub_pages.service_page`: Bookings service page. Variables: `slug`. + `wix.online_programs.sub_pages.online_program`: Online Programs program page. Variables: `slug`. + `wix.forum.sub_pages.category`: Forum category page. Variables: `slug`. + `wix.forum.sub_pages.post`: Forum post page. Variables: `categorySlug`, `postSlug`. + `wix.groups.sub_pages.group`: Groups group page. Variables: `groupId`, `tabName`. Other values aren't supported. - name: mapping | type: string | description: URL pattern for the item pages, relative to the site's base URL. Wrap variables in double curly braces, for example `shoes/{{slug}}`. The pattern must use every variable listed for its `key`, and no others. The pattern is saved in lowercase. Rules: up to 1,000 characters; no spaces, emoji, or URL-reserved characters; no leading or trailing slash; no empty segments; at most one variable per segment. The resulting URLs can't collide with another page on the site or with another URL mapping. Return type: PROMISE - name: key | type: string | description: Type of item page this URL mapping applies to, and the variables its `mapping` must use: + `wix.stores.sub_pages.product`: Stores product page. Variables: `slug`. + `wix.blog.sub_pages.post`: Blog post page. Variables: `slug`. + `wix.blog.sub_pages.category`: Blog category page. Variables: `slug`. + `wix.bookings.sub_pages.service_page`: Bookings service page. Variables: `slug`. + `wix.online_programs.sub_pages.online_program`: Online Programs program page. Variables: `slug`. + `wix.forum.sub_pages.category`: Forum category page. Variables: `slug`. + `wix.forum.sub_pages.post`: Forum post page. Variables: `categorySlug`, `postSlug`. + `wix.groups.sub_pages.group`: Groups group page. Variables: `groupId`, `tabName`. Other values aren't supported. - name: mapping | type: string | description: URL pattern for the item pages, relative to the site's base URL. Wrap variables in double curly braces, for example `shoes/{{slug}}`. The pattern must use every variable listed for its `key`, and no others. The pattern is saved in lowercase. Rules: up to 1,000 characters; no spaces, emoji, or URL-reserved characters; no leading or trailing slash; no empty segments; at most one variable per segment. The resulting URLs can't collide with another page on the site or with another URL mapping. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: | Description: The `key` isn't supported, doesn't match `urlMapping.key`, or a required field is missing. Details are in `fieldViolations`. HTTP Code: 409 | Status Code: ALREADY_EXISTS | Application Code: URL_MAPPER_SAVE_CONFLICT | Description: Another write to the site's URL mappings happened at the same time. Nothing is saved. Retry. HTTP Code: 409 | Status Code: ALREADY_EXISTS | Application Code: URL_MAPPER_ALREADY_EXISTS | Description: There is already a URL mapping with this `key`. To change it, call [Update URL Mapping](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/update-url-mapping.md). HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: | Description: The `mapping` pattern breaks a pattern rule (see `mapping`), for example it's missing a required variable, uses an unknown one, or collides with another page. Details are in `fieldViolations`. ``` ### Examples ### createUrlMapping ```javascript import { urlMappings } from '@wix/seo'; async function createUrlMapping(key,urlMapping) { const response = await urlMappings.createUrlMapping(key,urlMapping); }; ``` ### createUrlMapping (with elevated permissions) ```javascript import { urlMappings } from '@wix/seo'; import { auth } from '@wix/essentials'; async function myCreateUrlMappingMethod(key,urlMapping) { const elevatedCreateUrlMapping = auth.elevate(urlMappings.createUrlMapping); const response = await elevatedCreateUrlMapping(key,urlMapping); } ``` ### createUrlMapping (self-managed) Self-managed SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { urlMappings } from '@wix/seo'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { urlMappings }, // Include the auth strategy and host as relevant }); async function createUrlMapping(key,urlMapping) { const response = await myWixClient.urlMappings.createUrlMapping(key,urlMapping); }; ``` ---