> 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 # UpdateUrlMapping # Package: seo # Namespace: UrlMappingWriterService # Method link: https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/update-url-mapping.md ## Permission Scopes: Manage SEO Settings: SCOPE.PROMOTE.MANAGE-SEO ## Introduction Replaces the URL mapping for one type of item page. The site must already have a URL mapping for the key. To add one, call [Create URL Mapping](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/create-url-mapping.md). The change is live on the site right away. On a published site, the 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: updateUrlMapping Description: Replaces the URL mapping for one type of item page. The site must already have a URL mapping for the key. To add one, call [Create URL Mapping](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/create-url-mapping.md). The change is live on the site right away. On a published site, the 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: PUT # 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: UpdateUrlMappingResponse - name: urlMapping | type: UrlMapping | description: Updated 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: 404 | Status Code: NOT_FOUND | Application Code: URL_MAPPER_NOT_FOUND | Description: Couldn't find the URL mapping for the `key`. To add one, call [Create URL Mapping](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/create-url-mapping.md). 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: 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 ### Change the URL pattern for Stores product pages Replaces the existing pattern `shoes/{{slug}}`, so the product with the slug `red-shoes` moves to `/products/shoes/red-shoes`. ```curl curl -X PUT \ '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": "products/shoes/{{slug}}" } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.seo.urlMappings.updateUrlMapping(key, urlMapping) Description: Replaces the URL mapping for one type of item page. The site must already have a URL mapping for the key. To add one, call [Create URL Mapping](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/create-url-mapping.md). The change is live on the site right away. On a published site, the 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 whose URL mapping to update. 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: 404 | Status Code: NOT_FOUND | Application Code: URL_MAPPER_NOT_FOUND | Description: Couldn't find the URL mapping for the `key`. To add one, call [Create URL Mapping](https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/create-url-mapping.md). 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: 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 ### updateUrlMapping ```javascript import { urlMappings } from '@wix/seo'; async function updateUrlMapping(key,urlMapping) { const response = await urlMappings.updateUrlMapping(key,urlMapping); }; ``` ### updateUrlMapping (with elevated permissions) ```javascript import { urlMappings } from '@wix/seo'; import { auth } from '@wix/essentials'; async function myUpdateUrlMappingMethod(key,urlMapping) { const elevatedUpdateUrlMapping = auth.elevate(urlMappings.updateUrlMapping); const response = await elevatedUpdateUrlMapping(key,urlMapping); } ``` ### updateUrlMapping (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 updateUrlMapping(key,urlMapping) { const response = await myWixClient.urlMappings.updateUrlMapping(key,urlMapping); }; ``` ---