URL Mapping

The getUrlMapping endpoint allows headless storefronts to support localized, user-friendly URLs based on URL rules and URL redirects 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

Before you use the getUrlMapping endpoint:

• If you want to use the getUrlMapping to apply rules and redirects, set up your URL rules and/or URL redirects in Business Manager.
• Add the sfcc.shopper-seo scope to a SLAS API Client.

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.

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

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

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

1{
2    "refinements": {
3        "refinementColor": "Blue"
4    }
5    "resourceId": "new-arrivals-tops",
6    "resourceType": "category"
7}

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
• Create a Redirect from a B2C Commerce URL

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.

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

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.

1{
2  "additionalUrlParams": "utm_source=newsletter",
3  "copySourceParams": true,
4  "destinationUrl": "/sales?lang=en_GB&utm_source=newsletter",
5  "resourceId": "sales",
6  "resourceType": "category",
7  "statusCode": "302"
8}

• 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 and Create a Redirect from a B2C Commerce URL.
• 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.
  • If there’s a URI redirect, resourceId and resourceTypeare 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.

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

To resolve URL conflicts for generated URLs, see:

• URL Generation and Conflict Resolution for B2C Commerce
• Use the SEO URL General Tab

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 and the hooks for getUrlMapping in the Hook List.

• getUrlMapping API reference
• UrlMapping type reference
• Routing
• PWA Kit Documentation

j

Announcements

Choose Your B2C Commerce Storefront Type

B2C Commerce

SCAPI

Why Use SCAPI

Base URL and Request Formation

Authorization

Quick Start

General Guidance

Develop

Use SCAPI with MuleSoft

Use the Admin API

Use the Shopper API

Shopper Login (SLAS)

Shopper Context

Build Baskets and Place Orders

Promotion Types and Requirements

Agentic MCP Shopper Tools Quick Start (Pilot)

URL Mapping

Extend

Secure Your Site

Optimize Performance

Troubleshoot

SCAPI Specifications

Storefront Next

Composable Storefront

Storefront Reference Architecture (SFRA)

Commerce Apps ISV Developer Guide

B2C Commerce Solutions

B2C Commerce Release Notes

B2C Commerce Reference Information

Ask the Community