> 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 # BuildCustomizedUrl # Package: seo # Namespace: UrlMappingReaderService # Method link: https://dev.wix.com/docs/api-reference/business-management/seo/url-mapping-v1/build-customized-url.md ## Permission Scopes: View google ads campaigns: SCOPE.PROMOTE.VIEW-GOOGLE-ADS ## Introduction Builds item page URLs from the site's URL mapping for a key. Each item in `itemsData` gets one URL, in the same order. The site must have a URL mapping for the key. --- ## REST API ### Schema ``` Method: buildCustomizedUrl Description: Builds item page URLs from the site's URL mapping for a key. Each item in `itemsData` gets one URL, in the same order. The site must have a URL mapping for the key. URL: https://www.wixapis.com/promote/url-mapper/reader/v1/url-mapping/build Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: key, itemsData Method parameters: param name: itemsData | type: array | description: Items to build URLs for. Each item must include every variable the key requires. Up to 10,000 items. | required: true | validation: minItems 1, maxItems 10000 - name: itemData | type: object | description: Variable values for the item, keyed by variable name without the curly braces. For example, `{"slug": "red-shoes"}` turns the pattern `shoes/{{slug}}` into `shoes/red-shoes`. Values are inserted as is, without URL encoding. Send URL-safe values: a `/` in a value adds a path segment, and spaces or characters like `?` and `#` break the URL. | validation: format map param name: key | type: key | description: Type of item page to build URLs for. See `UrlMapping.key` for supported values. Other values aren't supported. | required: true param name: options | type: BuildCustomizedUrlOptions | description: Options for building URLs. - name: baseUrl | type: string | description: Prefix added before each built URL, for example `https://www.my-store.com/`. Default: no prefix. URLs are returned relative to the site's base URL and start with `/`, for example `/shoes/red-shoes`. Return type: BuildCustomizedUrlResponse - name: urls | type: array | description: Built URLs, in the same order as `itemsData` in the request. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: | Description: The `key` isn't supported, or an item is missing a variable the key requires. 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`. ``` ### Examples ### Build full product page URLs Builds one URL per item from the site's pattern `products/shoes/{{slug}}`, in the same order as `itemsData`, with `baseUrl` added before each URL. ```curl curl -X POST \ 'https://www.wixapis.com/url-mapper/reader/v1/url-mapping/build' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "key": "wix.stores.sub_pages.product", "itemsData": [ { "itemData": { "slug": "red-shoes" } }, { "itemData": { "slug": "blue-sneakers" } } ], "options": { "baseUrl": "https://www.my-store.com/" } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.seo.urlMappings.buildCustomizedUrl(key, options) Description: Builds item page URLs from the site's URL mapping for a key. Each item in `itemsData` gets one URL, in the same order. The site must have a URL mapping for the key. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: key, options.itemsData, options Method parameters: param name: key | type: string | description: Type of item page to build URLs for. See `UrlMapping.key` for supported values. Other values aren't supported. | required: true param name: options | type: BuildCustomizedUrlOptions none | required: true - name: itemsData | type: array | description: Items to build URLs for. Each item must include every variable the key requires. Up to 10,000 items. | required: true | validation: minItems 1, maxItems 10000 - name: itemData | type: object | description: Variable values for the item, keyed by variable name without the curly braces. For example, `{"slug": "red-shoes"}` turns the pattern `shoes/{{slug}}` into `shoes/red-shoes`. Values are inserted as is, without URL encoding. Send URL-safe values: a `/` in a value adds a path segment, and spaces or characters like `?` and `#` break the URL. | validation: format map - name: options | type: BuildCustomizedUrlOptions | description: Options for building the URLs. - name: baseUrl | type: string | description: Prefix added before each built URL, for example `https://www.my-store.com/`. Default: no prefix. URLs are returned relative to the site's base URL and start with `/`, for example `/shoes/red-shoes`. Return type: PROMISE - name: urls | type: array | description: Built URLs, in the same order as `itemsData` in the request. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: | Description: The `key` isn't supported, or an item is missing a variable the key requires. 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`. ``` ### Examples ### buildCustomizedUrl ```javascript import { urlMappings } from '@wix/seo'; async function buildCustomizedUrl(key,options) { const response = await urlMappings.buildCustomizedUrl(key,options); }; ``` ### buildCustomizedUrl (with elevated permissions) ```javascript import { urlMappings } from '@wix/seo'; import { auth } from '@wix/essentials'; async function myBuildCustomizedUrlMethod(key,options) { const elevatedBuildCustomizedUrl = auth.elevate(urlMappings.buildCustomizedUrl); const response = await elevatedBuildCustomizedUrl(key,options); } ``` ### buildCustomizedUrl (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 buildCustomizedUrl(key,options) { const response = await myWixClient.urlMappings.buildCustomizedUrl(key,options); }; ``` ---