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.

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:

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:

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.

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.

  • The getUrlMapping endpoint:
  • 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.
    • Ensure 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 Cloud 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:

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.