URL Rules URL Syntax

You can define how your storefront URLs look in Salesforce B2C Commerce via three types of URL syntax: standard B2C Commerce URL syntax, SEO URL syntax, or the deprecated search-friendly URL syntax. The syntax you use depends on which Business Manager module you have enabled.

Note: You can't enable both URL Rules and SEO Support. Salesforce recommends the URL Rules module because it provides greater configuration flexibility.

This page describes the URL rules syntax, and illustrates how it differs from the standard syntax and the SEO Standard.

Site URL Format

The site URL format is defined as follows:
<hostname>/<endpoint>

This is the URL for any host name that doesn't end in .demandware.net.

Example: yoursite.com/mens

*.demandware.net/s/<site-name>/<endpoint>

This is the URL for any host name ending in .demandware.net or localhost.

Example: yoursite-test-ex01-dw.demandware.net

Within B2C Commerce, you can configure and customize the endpoint of a URL.

Production instance URLs

On Production instances, B2C Commerce URLs look as follows:

Example Type URL
pipeline URL
www.SiteGenesis.com/cart
category URL
www.SiteGenesis.com/men
product URL
www.SiteGenesis.com/shoes/sandals/red/water-sandal
custom URL
www.SiteGenesis.com/entertain

Sandbox, Staging, and Development Instance URLs

If no alias is defined on a Staging, Development, or Sandbox instances, URLs have *.demandware.net as the host name, followed by the prefix /s, followed by the site name. The actual endpoint is identical to the one on the Production instance. This allows multi-site retailers to view the configured endpoints for each of their sites.

Example Type URL
pipeline URL
*.demandware.net/s/SiteGenesis/cart
category URL
*.demandware.net/s/SiteGenesis/men
product URL
*.demandware.net/s/SiteGenesis/shoes/sandals/red/water-sandal
custom URL
*.demandware.net/s/SiteGenesis/entertain
If an alias is configured on Staging, Development, or Sandbox instances, the host name doesn't include .demandware.net and therefore the URL is the same as on Production, in that it does not include the site name.

General Syntax Tips

To understand how requesting URLs are evaluated and resolved, see URL Evaluation and Resolution.

Case Sensitivity

URLs can be resolved even if there are case differences in the URL.

Unencoded Characters in the URL

URLs can be resolved if the following unencoded characters are in the URL:
, @ ) ! $ ' (  ~

B2C Commerce automatically encodes these characters.

Spaces

The use of spaces in a URL rule is for readability only. The absence of spaces around rule elements makes no difference whether your URL rule verifies. Commas however, are important because they separate the elements. The absence of a comma can determine whether your rule verifies.

Context

When defining URL rules, be aware of context when you specify the source of the attributes. For a category rule, the source is a category, so you can use a rule such as the following:

[ [ constant, const ], /, [ category-path, [ attribute, ID ], - ]]

In this rule, you are defining a constant and the category path to be used in every URL. The attribute in this rule is an attribute of the category, and thus the category ID.

In a product rule, however, the source is a product, so you must declare category as source for category-path, as in the following rule:

[ [ constant, const ], /, [ category, [ category-path, [ attribute, ID ], - ] ]]

If you define the following product rule, then the constant const111 applies as a constant and category applies as you have specified in the category rule.

[ [ constant, const111 ], /, [ category] ]

You need to be careful when defining the product rule because any usage of category is as you defined it in the category rule. For example, if you specify the category rule to result in /const222/electronics/ and then you use [ [ constant, const111 ], /, [ category] ] to define a product rule, then the results are as follows:

/const111/const222/electronics/008884303996.html 

Multi-Value Attributes

When configuring SEO rules to generate URLs for products, content, categories, and folders, you can specify multi-value attributes using the Enum-of-String and Set-of-String types in a way that is similar to single-value attributes. In the following example, color is an Enum-of-String product attribute.

[ [ category, [ attribute, displayName ] ], /, [ attribute, custom.color], /, [ attribute, name ] ] 

All values of the multi-value attribute are included into the URL. The values are concatenated by a blank, or the defined replacement character of blank (for example ‘-‘). The localized display value is used for the Enum values, unless no display value is defined, in which case the value is used.

An example URL, generated based on the rule above, is as follows:

/mens-shoes/black-yellow/spring-sneaker/12345.html   

Category URLs

URL Rules site URLs can be enabled for category pages, and merchants can configure the category URL endpoints on the URL Rules page Catalog URLS tab.

Standard B2C Commerce Category URL Structure

A category URL with all SEO modules disabled looks as follows:
www.sitegenesis.com/on./demandware.store/Sites-SiteGenesis-Site/default/Search-Show?cgid=mens-clothing-shorts 

SEO Support Module Category URL Structure

A category URL with the deprecated SEO Support module enabled looks as follows:
www.sitegenesis.com/mens-clothing-shorts,default,sc.html 

URL Rules module category URL Structure

A category URL with the URL Rules module enabled looks as follows:

URL Rule:
[ category-path, [ attribute, displayName ], - ] 

This rule shows the category path and display name for the category, with a dash for the delimiter for spaces in the category name.

Example URL:
www.sitegenesis.com/mens-clothing-shorts

Category URL Rule

To define the content of a category URL, you can combine multiple elements and specify the delimiters between the elements.
[ [attribute_1], del , [attribute2], del , [attribute_3] ]
The rule can contain up to five elements. Category elements have four types: attributes, constant, category-path, category-parent. (See below for a specification of each of those element types.)
Examples:
[ [constant, shop], / , [category-path, [attribute, ID], -] ]
www.sitegenesis.com/shop/mens-clothing-shorts/ 

Configuring Categories/Folders

If you would like to exclude certain categories or folders from the URLs, you can use the path exclusion category syntax.

A simple syntax of:
[ category-path, [attribute, displayName], /, [3,4]]
will take a category tree of brand > sale > men > shoes > leather, and display the URL as:
www.sitegenesis.com/brand/sale/leather

This syntax is available for configuration for the following URL rule attributes:

  • category-path
  • category-path-with-offline
  • folder-path
  • folder-path-with-offline
The following configuration options are available to define category URLs:
Option Definition
attribute This element is used to include any attribute of the category or folder, such as ID, name, or any custom attribute. A default value can be defined and is used if either the attribute or the attribute value is undefined for the category. If no default value is specified, the parameter is omitted from the URL.
[ attribute, custom.categoryURL ]
www.sitegenesis.com/mens-shorts
[ [category-path, -], / , [attribute, custom.url_param] ] 
www.sitegenesis.com/mens-clothing-shorts/custom 
category-parent

This element is used to include the name or other attribute of a category and of its direct parent category. You can specify the attribute and the delimiter.

[ category-parent, [attribute, ID], - ]
www.sitegenesis.com/clothing-shorts
[ category-parent, [attribute, displayName], / ]
www.sitegenesis.com/clothing/shorts
 [ category-parent, [attribute, custom.customURLName], + ] 
www.sitegenesis.com/clothing+shorts
category-parent-with-offline

This element is used to include the name or other attribute of an offline category and of its direct offline parent category. You can specify the attribute and the delimiter.

[ category-parent-with-offline, [attribute, ID], - ]
www.sitegenesis.com/sale/clothing-shorts
[ category-parent-with-offline, [attribute, displayName], / ]
www.sitegenesis.com/sale/clothing/shorts
 [ category-parent-with-offline, [attribute, custom.customURLName], + ] 
www.sitegenesis.com/sale/clothing+shorts
category-path

This element type is used to include the name or other attribute of a category and all of its parent categories. You can specify the attribute and the delimiter.

[ category-path, [attribute, ID], - ]
www.sitegenesis.com/mens-clothing-shorts
[ category-path, [attribute, displayName], / ]
www.sitegenesis.com/mens/clothing/shorts
[ category-path, [attribute, custom.customURLName], + ]
www.sitegenesis.com/mens+clothing+shorts 
Using the configurable path exclusion URL logic, use the following syntax:
[ category-path, [attribute, displayName], /, [2]] 
www.sitegenesis.com/mens/shorts 
category-path-with-offline

This element type is used to include the name or other attribute of an offline category and all of its offline parent categories. You can specify the attribute and the delimiter.

[ category-path-with-offline, [attribute, ID], - ]
www.sitegenesis.com/sale/mens-clothing-shorts
[ category-path-with-offline, [attribute, displayName], / ]
www.sitegenesis.com/sale/mens/clothing/shorts
[ category-path-with-offline, [attribute, custom.customURLName], + ]
www.sitegenesis.com/sale/mens+clothing+shorts 
constant

This element is used to include an arbitrary text element.

[ [ constant, cat ], /, [ category-path, [ attribute, ID ], + ] ]
 www.sitegenesis.com/cat/mens+mens-clothing+mens-clothing-shorts/custom 
displayName This element is used to specify the display name of an attribute.
folder-parent

This element type is used to include the name or other attribute of a folder and its direct parent folder. You can specify the attribute and the delimiter.

[ folder-parent, [ attribute, displayName ], / ]

folder-parent-with-offline

This element type is used to include the name or other attribute of an offline folder and its direct offline parent folder. You can specify the attribute and the delimiter.

[ folder-parent-with-offline, [ attribute, displayName ], / ]

folder-path

This element type is used to include the name or other attribute of a folder. You can specify the attribute and the delimiter.

[ folder-path, [ attribute, displayName ], / ]
Using the configurable path exclusion URL logic, use the following syntax:
[ folder-path, [ attribute, displayName ], /, [2]]
www.sitegenesis.com/mens/shorts 
folder-path-with-offline

This element type is used to include the name or other attribute of an offline folder. You can specify the attribute and the delimiter.

[ folder-path-with-offline, [ attribute, displayName ], / ]
Using the configurable path exclusion URL logic, use the following syntax:
[ folder-path-with-offline, [ attribute, displayName ], /,[2]]
www.sitegenesis.com/mens/shorts 
A setting is provided to optionally append a trailing slash to category URLs in the URL Rules page Catalog URLs tab.
www.sitegenesis.com/mens-shorts (trailing slash off)
www.sitegenesis.com/mens-shorts/ (trailing slash on) 

Localized URLs

If a site is localized, then a separate URL exists for each site locale, for example:
www.sitegenesis.com/en/mens-clothing-shorts
www.sitegenesis.com/de/herren-kleidung-shorts

You can control how the locale is specified for the URL in the URL Rules page Settings tab. You can set whether your sites are localized using the Global Preferences Locales page.

Offline Categories/Folders

URL generation behavior for rules using a category path typically skips offline categories, which can result in categories flagged as conflicting, even when they actually are not in conflict. This can occur when a merchant needs to keep categories offline until a specific event. They typically use a standard structure for subcategory names within each event-related category, for example, MothersDay/sale, ValentinesDay/sale, Easter/sale.

For example:

Because both A and B are offline, a-sale and b-sale will have the same URL sale. This pollutes the URL conflicts log with wrongly identified conflicts, making it difficult to identify genuine URL conflicts.

You can define rules that obtain information from offline categories/folders, as shown in these examples:

[ category-path-with-offline, [ attribute, displayName ], / ]
[ category-parent-with-offline, [ attribute, displayName ], / ]
[ folder-path-with-offline, [ attribute, displayName ], / ]
[ folder-parent-with-offline, [ attribute, displayName ], / ]

For example, the sale category is offline, and this is the category taxonomy:

host.com/sale/mens
host.com/mens

When offline categories are recognized, the results are not in conflict: no URL conflict resolution is required.

host.com/sale/mens
host.com/mens

When offline categories are not recognized, conflicts result, which can be handled via URL conflict resolution.

host.com/mens-1
host.com/mens-2 

Overriding automatically generated category URLs

Based on the category URL rule, B2C Commerce automatically generates category URLs. You can also define the URL endpoint for any category.

For example, the following rule:
[ [ attribute, displayName ] ]
leads to a conflict for the Sale category in Mens > Clothing > Sales and Womens > Clothing > Sales, and the URL generator automatically appends an index number to the generated URLs:
  • Generated URL of Mens > Clothing > Sales: www.sitegenesis.com/sales-1
  • Generated URL of Womens > Clothing > Sales: www.sitegenesis.com/sales-2
You can override the generated URLs for Mens > Clothing > Sales or Woens > Clothing > Sales. The PageURL attribute for the category is used as the endpoint, instead of the endpoint generated by the rule.

Example 1: Mens Sales

Assume the generated URL of Mens > Clothing > Sales is:
www.sitegenesis.com/sales-1 
However, if you set the PageURL attribute of the Mens > Clothing > Salescategory to mens-sales, then the actual URL of Mens > Clothing > Salesis:
www.sitegenesis.com/mens-sales 

Example 2: Womens Sales

Assume the generated URL of Womens > Clothing > Sales is:
www.sitegenesis.com/sales-2 
However, if you populate the PageURL attribute for the category Womens > Clothing > Sales with womens-sales, then the actual URL of Womens > Clothing > Sales is:
www.sitegenesis.com/womens-sales

Product URLs

URLs can be enabled for product pages. The product URL endpoints are configured based on a simple rule syntax.

Product URL Format

Product URLs are enabled using a preference in Business Manager and configured on the URL Rules Page Catalog URLs tab. In the following example, a product URL contains its category, its name, and the product ID. The product ID is mandatory and is appended to each product URL, along with the extension .html.

URL Rule:
 [ category, /, [ attribute, name ] ]
Example URL:
www.sitegenesis.com/mens-clothing-shorts/straight-fit-shorts/8353682.html 
You can configure if the delimiter in front of the product ID is '/' or '-'. If the delimiter is '-', but a product name contains '-', then B2C Commerce automatically uses the '/' delimiter for the URL of this product. www.sitegenesis.com/crowne-shorts-brown/83536828.html instead of www.sitegenesis.com/crowne-shorts-brown-83536828.html

Product URL Rule

To define the content of a product URL, you can combine multiple elements and specify the delimiters between the elements.
[ [attribute_1], del , [attribute2], del , [attribute_3] ] 
The rule can contain up to five elements. Elements have two types: attributes and category.

The following configuration options are available to define product URL endpoints:

Option Definition
category Examples :
[ ]
www.sitegenesis.com/83536828.html

For the following rule, select the Use '-' as Product ID separator instead of '/' checkbox.

[ [category], - , [attribute, name] ]
www.sitegenesis.com/shop/mens-clothing-shorts-beach-shorts-83536828.html 

If the checkbox isn't selected, you see the following:

www.sitegenesis.com/shop/mens-clothing-shorts-beach-shorts/83536828.html
attribute This element is used to include category information. Examples The category URL as generated by the category URL generator (see previous section). This rule must be used when the URL is supposed to “show the product in category context”.
[ [category] ]
www.sitegenesis.com/mens+clothing+shorts/83536828.html
The display name of the category.
[ [category, [attribute, displayName]] ]
www.sitegenesis.com/shorts/83536828.html
The URL name of the category and an extra custom attribute of the category.
[ [category], / , [category, [attribute, customAttr] ]
www.sitegenesis.com/mens+clothing+shorts/custom-cat-value/83536828.html 
constant

This element is used to include an arbitrary text element.

[ constant, cat ]
www.sitegenesis.com/cat/83536828.html

You can also use the category with the constant element.

[ [ constant, cat ], /, [category] ]
www.sitegenesis.com/cat/shorts/83536828.html

How the [category] is determined for the product URL

B2C Commerce determines the category in the URL using the following logic:

  1. Use the primary category of the product in the storefront catalog.

    If the product doesn't have a primary category assigned or the primary category doesn't exist in the storefront catalog, move to the next step.

  2. Use the classification category of the product in the storefront catalog.

    If the product doesn't have a classification category assigned or the classification category does not exist in the storefront catalog, move to the next step.

  3. Use the first category in the storefront catalog ever assigned to the product. The product must be assigned to at least one category in the storefront catalog to be available on the site.

Overriding automatically generated product URLs

Similar to category URLs, you can override the product URLs generated by the URL generator by using the PageURL attribute.

Generated URL of product: www.sitegenesis.com/sports-shoe-red/1234.html

PageURL attribute of product: mckenzie-sports-shoe

Actual URL of Mens > Clothing > Sales: www.sitegenesis.com/mckenzie-sports-shoe/1234.html

Content and Folder URLs

URL definition/generation for folders and content assets functions the same way as categories and products. See the URL Rules page, Content URLs page in Business Manager for folder and content URL rule examples.
Note: Folders don't generally have a landing page, nor are they usually rendered as part of other pages on the storefront. However, if you specify a URL syntax for them, the URLs that are generated might conflict with category URLs. For example, for gift registry or sale. For this reason, you might want to not specify a URL syntax for folders. The same doesn't hold true for content assets and therefore Salesforce recommends that you optimize your content asset URLs.

Pipeline Aliases

All page URLs except product, category, and content pages show a pipeline in the URL. For pipeline pages, you can create URLs that don't contain /on/demandware.store by mapping a pipeline name to an alias in Business Manager. Pipeline page URLs look similar to:
www.sitegenesis.com/on/demandware.store/Sites-SiteGenesis-Site/default/Account-Show
www.sitegenesis.com/on/demandware.store/Sites-SiteGenesis-Site/default/Search-Show?q=shoes
In Business Manager, you can define mappings for any of your pipelines.
URL Pipeline
account Account-Show
search Search-Show
wishlist Wishlist-Show
If new URLs are turned on, and a mapping has been defined for a pipeline, the URL changes to the following format:
www.sitegenesis.com/account
www.sitegenesis.com/search?q=shoes

Locale

You control if and how the locale/language identifier is represented in all storefront URLs, by selecting a locale option: None, Hostname, URL Parameter, or Path.

None

This option is used if the site has only one presentation language. Incoming URLs are not examined for any language identifier. All pages are delivered in the site default locale. B2C Commerce assumes that there is only one allowed site locale, but if there are multiple, the default one is used. Generated URLs will not contain any locale identifier.
www.example.com/mens 

Hostname

The presentation language is determined by examining the host name of the incoming URL. You must configure a mapping between host names and site locales, for example de.example.com - de_DE, www.example.com - en_US, es.example.com - es_US. Multiple host names can be mapped to one locale. If no mapping exists for a host name, the page is delivered in the default site locale.
www.example.com/mens
de.example.com/mens

URL Parameter

The presentation language is determined by examining a standard URL parameter of the incoming URL. The default parameter name is "locale", ?locale=en-US, and you can specify another query string parameter name, such as "lang". You can configure a mapping of a language code for any custom string to a site locale, for example default <> en_US, es <> es_US. If no mapping exists, it's assumed that the locale ID is specified. If the locale id doesn't match any of the allowed site locales, the page is delivered in the default site locale. Generated URLs contain the same URL parameter as the incoming URL if the prefix was valid, or the prefix defined for the site default locale if the prefix was invalid. You can define the name of the URL parameter.
www.example.com/mens?locale=en-US
de.example.com/mens?lang=en
www.example.com/mens?lang=spanish

Path

The presentation language is determined by examining the first element in the URL path. You can configure a mapping of the URL language code to a site locale, for example default-> en_US, en -> en_US. If no mapping exists, it's assumed that the locale ID is specified in the URL. If the locale id doesn't match any of the allowed site locales, the page is delivered in the default site locale.
www.example.com/de/mens
www.example.com/en/mens 

Define a double-path locale by specifying the first value, the '/' character, and then the second value. For example, en/US or de/DE, which results in the following:

www.example.com/en/US/mens
www.example.com/de/DE/mens
Note: When using a double-path, the locale mapping of the URL Parameter type can't contain '/'. See Using the SEO URLs Settings Tab.

Related Links

URL Syntax

X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used and to tailor advertising. By continuing to use this site you are giving us your consent to do this.