---
schema_version: "1"
id: 50064bb87cd13dca53b425e22dc59dbd7f3c72eecf15167807d607952dd5e50c
title: URL Mapping
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/guides/url-resolution.md
canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/url-resolution.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: e658341da9e734fa89f61b3c51137f6a6cfca645a1d342aa5d03bbff6eff731c
products:
  - Composable Storefront
  - Salesforce APIs
---
# URL Mapping

The [getUrlMapping](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo?meta=getUrlMapping) endpoint allows headless storefronts to support localized, user-friendly URLs based on [URL rules](https://help.salesforce.com/s/articleView?id=cc.b2c_using_url_rules_for_seo.htm&type=5) and [URL redirects](https://help.salesforce.com/s/articleView?id=cc.b2c_url_redirects.htm&type=5) set up in Business Manager. This endpoint helps you to increase your site traffic and improve site navigation.

For example, you identify “new arrivals” as a valuable search term and you add a route (URL: `www.example.com/new-arrivals`) to your storefront. You can use a rule in Business Manager to map that URL to a category list page for new arrivals. Then you can use the getUrlMapping endpoint to apply the rule when a shopper:

- Searches for new arrivals
- Clicks or types in this URL: `www.example.com/new-arrivals`

## Prerequisites

Before you use the getUrlMapping endpoint:

- If you want to use the getUrlMapping to apply rules and redirects, set up your [URL rules](https://help.salesforce.com/s/articleView?id=cc.b2c_using_url_rules_for_seo.htm&type=5) and/or [URL redirects](https://help.salesforce.com/s/articleView?id=cc.b2c_url_redirects.htm&type=5) in Business Manager.
- Add the `sfcc.shopper-seo` scope to a [SLAS API Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html).

## Sample Call

In this example, we use a cURL command to call the getUrlMapping endpoint to resolve this URL that a shopper clicked or typed in: `www.example.com/blue/new-arrivals/tops`.

```bash
curl "https://$CODE.api.commercecloud.salesforce.com/site/shopper-seo/v1/organizations/$ORG/url-mapping' \
  --get \
  --header "Authorization: Bearer $TOKEN" \
  --data "siteId=$SITE" \
  --data "locale=en-GB" \
  --data-urlencode "urlSegment=blue/new-arrivals/tops"
```

The URL's path without a leading slash is passed as the `urlSegment` parameter.

## Sample Response

As shown in the response, the URL is mapped to a category called new-arrivals-tops:

```json
{
    "refinements": {
        "refinementColor": "Blue"
    }
    "resourceId": "new-arrivals-tops",
    "resourceType": "category"
}
```

## URL Redirects

You can also use the getUrlMapping endpoint to apply URL redirects that you set up in Business Manager. This helps you to carry out temporary product launches or seasonal campaigns and improve shopper experience.

For more information, see:

- [URL Redirects for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_url_redirects.htm&type=5)
- [Create a Redirect from a B2C Commerce URL](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_a_redirect_from_a_digital_url.htm&type=5)

### Sample Call

In this example, we use a cURL command to call the getUrlMapping endpoint to redirect this URL that a shopper clicked or typed in: `www.example.com/cyber-monday`. For instance, you had a campaign for a past Cyber Monday. That page accumulated significant SEO rank that you want to keep. You set up a redirect to temporarily send shoppers from the old Cyber Monday URL to a new campaign page you're launching until your new Cyber Monday page is available.

```bash
curl "https://$CODE.api.commercecloud.salesforce.com/site/shopper-seo/v1/organizations/$ORG/url-mapping' \
  --get \
  --header "Authorization: Bearer $TOKEN" \
  --data "siteId=$SITE" \
  --data "locale=en-GB" \
  --data-urlencode "urlSegment=cyber-monday"
```

### Sample Response

In this sample response, the `urlSegment` redirects to a category called sales. The statusCode 302 tells you that it’s a temporary redirect and the destinationUrl field tells you where to redirect the shopper. Since `copySourceParams` is set to `true` (Yes in Business Manager), the `additionalUrlParams` value set to `utm_source=newsletter` is added to the end of the `destinationUrl`. In this example, we use UTM (Urchin Tracking Module) parameters to track marketing efforts and indicate that traffic came from a newsletter.

```json
{
  "additionalUrlParams": "utm_source=newsletter",
  "copySourceParams": true,
  "destinationUrl": "/sales?lang=en_GB&utm_source=newsletter",
  "resourceId": "sales",
  "resourceType": "category",
  "statusCode": "302"
}
```

## Considerations

- The getUrlMapping endpoint:
  - Can resolve URLs for these types of resources: product, category (including category refinements), and content assets (Page Designer or Content Slot assets).
  - Applies only to the types of rules and redirects described in [URL Rules for SEO](https://help.salesforce.com/s/articleView?id=cc.b2c_using_url_rules_for_seo.htm&type=5) and [Create a Redirect from a B2C Commerce URL](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_a_redirect_from_a_digital_url.htm&type=5).
- You can pass a locale into the getUrlMapping endpoint. However, if you don’t, the endpoint falls back to the default locale of the site as configured in Business Manager.
- URL Redirects:
  - If there’s a conflict between your URL redirects and your URL rules for SEO, the URL redirects take precedence. In this scenario, the `resourceId` and `resourceType` will refer to the Commerce Cloud object (product, category, or content asset) and destination type that you configured in Business Manager.
  - Make sure that, before executing routing logic, your code considers the presence of these redirect-related outputs: `additionalUrlParams`, `copySourceParams`, `destinationUrl`, and `statusCode`. The presence of these fields means that a redirect is configured for the requested path. For more details, see the [getUrlMapping API reference](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo?meta=getUrlMapping).
  - If there's a URI redirect, `resourceId` and `resourceType`are null.
  - The `destinationUrl` is based on your configuration in Business Manager: it's either a calculated value indicating the Commerce object (product, category, or content asset) URL or your specified URI. Note that an object's path may not necessarily match your headless storefront URLs but can be used as a reference for calculating your desired redirect path.

## Best Practices

These best practices apply to integrating getUrlMapping into a headless site:

- Add wildcard mappings to your routes flow as the final step in the sequence.
- By inserting this endpoint into your routes flow you‘re adding another database call to resolve requests on your website. To optimize for performance, we recommend that you:
  - Set long time-to-live (TTL) values for the getUrlMapping endpoint. (The default TTL is 12 hours.)
  - Use this endpoint as a fallback after attempting to resolve URLs with your routing engine. First try to use routes that are semantic and interpretable by your routing engine. For example: /categories/[categoryFriendlyName]/[categoryId].

## Troubleshooting

To resolve URL conflicts for generated URLs, see:

- [URL Generation and Conflict Resolution for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_url_generation_and_conflict_resolution.htm&language=en_us&type=5)
- [Use the SEO URL General Tab](https://help.salesforce.com/s/articleView?id=cc.b2c_using_the_seo_url_general_tab.htm&language=en_us&type=5)

## Advanced Usage

You can customize the behavior of the getUrlMapping endpoint by using these hooks:

- `dw.shop.seo.url_mapping.beforeGET`
- `dw.shop.seo.url_mapping.modifyGETResponse`

See [Customization with Hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html) and the hooks for getUrlMapping in the [Hook List](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hook_list.html).

## See Also

- [getUrlMapping API reference](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo?meta=getUrlMapping)
- [UrlMapping type reference](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo?meta=type%3AUrlMapping)
- [Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/routing.html)
- [PWA Kit Documentation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html)