All Collections
Store Setup
SEO & Analytics
Tweaking SEO-Friendly URLs in X-Cart 5.4.x
Tweaking SEO-Friendly URLs in X-Cart 5.4.x

Learn how to configure the clean URLs behaviour in an online store based on X-Cart 5.4.x.

Olga Tereshina avatar
Written by Olga Tereshina
Updated over a week ago

You can configure the behavior of SEO-friendly URLs in your X-Cart store via the file XCART_DIRECTORY/etc/config.php. For the required config settings, refer to the [clean_urls] section.

Here is the list of all the available settings and their default values:

  • use_language_url = "Y"

    ; Specify whether language codes need to be included in the clean 
    URLs of pages in languages other than your store's default
    language; for example, if the URL of a page in the default
    language is domain/sale, the URL of the same page in the German
    language will be formed as domain/de/sale.
    ; Possible values: "Y" (enables inclusion of language codes), "N"
    (disables inclusion of language codes)
    ; Be sure to re-deploy your store after readjusting this setting
    for the change to take effect.
    use_language_url = "Y"

  • default_separator = "-"

    ; Set the string to be used as the default separator for 
    autogenerated clean URLs.
    ; The string can consist of one or more characters.
    ; Only the "-" (hyphen) and "_" (underscore) characters are
    supported.
    ; Empty string is also allowed (default_separator = ""); if empty,
    clean URLs will be formed using hyphens.
    default_separator = "-"

  • capitalize_words = Off

    ; Specify whether clean URLs should use capitalization for every 
    starting letter of a word
    ; Readjusting this setting will not affect your existing clean
    URLs.
    capitalize_words = Off

  • use_unicode = Off

    ; Specify whether non-Latin characters should be allowed for 
    autogenerated clean URLs.
    ; Possible values: Off (only Latin chars will be used), On
    (Unicode chars will be used)
    ; Readjusting this setting will not affect your existing clean
    URLs.
    use_unicode = Off

  • canonical_product_clean_urls_format = "domain/product_clean_url"

    ; Canonical clean URL format for products
    ; Possible values:
    ; domain/product_clean_url
    ; domain/main_category_clean_url/product_clean_url
    ;
    canonical_product_clean_urls_format = "domain/product_clean_url"

  • category_clean_urls_format = "domain/parent/goalcategory/"

    ; Clean URL format for categories
    ; Possible values:
    ; domain/parent/goalcategory/
    ; domain/goalcategory/
    ; domain/parent/goalcategory.html
    ; domain/goalcategory.html
    ;
    ; Be sure to re-deploy your store after readjusting this setting
    for the change to take effect.
    ; Readjusting this setting will not affect your existing URLs.
    category_clean_urls_format = "domain/parent/goalcategory/"

  • product_clean_urls_format = "domain/goalproduct"

    ; Clean URL format for products
    ; Possible values:
    ; domain/goalproduct
    ; domain/goalproduct.html
    ;
    ; Be sure to re-deploy your store after readjusting this setting
    for the change to take effect.
    ; Readjusting this setting will not affect your existing URLs.
    product_clean_urls_format = "domain/goalproduct"

  • static_page_clean_urls_format = "domain/goalpage"

    ; Clean URL format for static pages
    ; Possible values:
    ; domain/goalpage
    ; domain/goalpage.html
    ;
    ; Be sure to re-deploy your store after readjusting this setting
    for the change to take effect.
    ; Readjusting this setting will not affect your existing URLs.
    static_page_clean_urls_format = "domain/goalpage"

    Note: Static pages = content pages.

  • sale_discount_clean_urls_format = "domain/goaldiscount"

    ; Clean URL format for sale offer pages
    ; Possible values:
    ; domain/goaldiscount
    ; domain/goaldiscount.html
    ;
    ; Be sure to re-deploy your store after readjusting this setting
    for the change to take effect.
    ; Readjusting this setting will not affect your existing URLs.
    sale_discount_clean_urls_format = "domain/goaldiscount"

  • vendor_clean_urls_format = "domain/goalvendor"

    ; Clean URL format for vendor pages
    ; Possible values:
    ; domain/goalvendor
    ; domain/goalvendor.html
    ;
    ; Be sure to re-deploy your store after readjusting this setting
    for the change to take effect.
    ; Readjusting this setting will not affect your existing URLs.
    vendor_clean_urls_format = "domain/goalvendor"

  • news_clean_urls_format = "domain/goalnews"

    ; Clean URL format for news pages
    ; Possible values:
    ; domain/goalnews
    ; domain/goalnews.html
    ;
    ; Be sure to re-deploy your store after readjusting this setting
    for the change to take effect.
    ; Readjusting this setting will not affect your existing URLs.
    news_clean_urls_format = "domain/goalnews"

  • brand_clean_urls_format = "domain/goalbrand"

    ; Clean URL format for brand pages
    ; Possible values:
    ; domain/goalbrand
    ; domain/goalbrand.html
    ;
    ; Be sure to re-deploy your store after readjusting this setting
    for the change to take effect.
    ; Readjusting this setting will not affect your existing URLs.
    brand_clean_urls_format = "domain/goalbrand"

Depending on the version of X-Cart you are using, the [clean_urls] section may look slightly different but supports the same formatting for the settings named above.


Important: Please use caution when switching the clean URL formats for your store's pages. For example, suppose you have more than one product category of the same name at different nesting levels, and you are switching the clean URL format from "domain/parent/goalcategory" or "domain/parent/goalcategory.html" to "domain/goalcategory" or "domain/goalcategory.html." In that case, it may get the same URL for all of them and render some of your store's category pages inaccessible.

Example: You set the store's category clean URL format to "domain/parent/goalcategory."

You have three categories named "Oils":

  • at the root level of your store website (this results in the clean URL example.com/oils),

  • in the category "Supplements" (example.com/supplements/oils);

  • in the category "Beauty" (example.com/beauty/oils).

You decide to readjust the category clean URL format from "domain/parent/goalcategory" to "domain/goalcategory."

When you do so, the clean URLs are re-generated for all your store's categories following the format "domain/goalcategory." You get the URL example.com/oils for all the three "Oils" categories mentioned above. After someone visits one of the category pages using the clean URL example.com/oils, they will not access any of the other two categories' pages. Even if you change the conflicting clean URLs for these categories manually to make them accessible again, your store visitors will continue getting onto the page they have already visited until they refresh the browser cache.


We recommend completing the clean URL tweaking before search engines index your store website. If you try to tweak the URLs after your website has been indexed, it may be problematic to set up the 301 redirect routing correctly.

Related pages:

Did this answer your question?