- Custom routes serve a template, a resource, or a redirect at a path you choose. A redirect is a custom route whose rule redirects.
- Country routes change what a route serves for visitors from particular countries. They work on custom routes and on built-in pages.
Every redirect is a sitemap route. To redirect a URL, create a custom route whose rule redirects, on the Sitemap screen or with the API. See Create a redirect with the API. Don’t use the older
/api/redirects endpoints. They aren’t part of the documented API, and the Sitemap screen doesn’t show what they create.Recommended: redirect marketing and legacy URLs
A marketing URL such as/tv-offer, or a path from a merchant’s previous website, is what customers without a rep type or click: from TV, print, ads, or old links. Redirect it to the Fluid product or page it stands for:
default rule redirects, so it answers at /tv-offer itself.
Members don’t use that URL. When a member shares, from the Fluid mobile app or their own links, they use credited paths such as /jordan-lee/products/beet-blend, so attribution works through the credit segment as usual. The marketing URL keeps working for everyone else, and the product keeps a single canonical address.
Choose by what the URL needs:
A redirect rule answers
301 (permanent) or 302 (temporary). Browsers and search engines remember a 301, so use 302 for a URL whose destination will change.
Credited and non-credited routes
Every custom route has one of two URL shapes:
A credited route behaves like any other storefront page: the credit segment carries attribution.
A non-credited route claims its first path segment for the company. Once
/spring-sale is a non-credited route, Fluid treats any request whose first segment is spring-sale as a custom-route request, not a credit segment.
Reserved paths
A custom route can’t use a built-in storefront path:shop, join, or anything under products/, pages/, collections/, categories/, media/, enrollments/, or libraries/. Those paths can still take country routes, but only as credited routes and never with a default rule.
What a route can serve
Each rule serves one of these:- A template. The page renders with a template from the rule’s own theme. Use a template for the page type the rule renders, such as a product template for a product. The admin offers only those.
- A resource. A product, page, media item, enrollment pack, category, or collection, rendered with the rule’s template.
- A built-in page. The home, shop, or join page.
- A redirect. A
301or302to the rule’s URL. - Nothing (disabled). A
404for visitors from the rule’s countries. A disabled rule can’t be thedefaultrule.
/spring-sale, and the page has no redirect hop.
How Fluid picks a rule
Country detection
Fluid decides the visitor’s country from the first of these it finds:- The
regionquery parameter, such as?region=CA. Use it to test; don’t put it in links you publish. - The country in the visitor’s saved locale, which the locale selector sets, such as
CAinfr_CA. - The visitor’s location, from the CDN’s geolocation headers.
- The company’s default country.
US.
Rule selection
For a route, Fluid then picks one active rule on the active theme:- A rule for the visitor’s country.
- The route’s
defaultrule. Only custom routes have one. - A rule for the company’s default country.
Country, not language
Rules are keyed by country only. Two visitors in Canada get the same rule whether they browse in English or French. To change language, translate the template rather than adding a rule: a template renders in the visitor’s language from its translations.Themes, caching, and propagation
- Only the active theme’s rules apply. A rule belongs to one theme. Rules on other themes apply only while someone previews that theme. When a merchant publishes a different theme, its routes need to exist on that theme too.
- Pages are cached per country and language. The CDN keeps a separate copy of a storefront page for each country and language.
- Changes take a few seconds to about 90 seconds to propagate. Saving a rule clears the CDN’s copies of that path. Non-credited routes also update a list the CDN keeps, which takes up to about 90 seconds to reach every edge.
Redirects
A redirect rule sends itsredirect_status_code, 301 or 302, to the rule’s redirect_url:
-
Status. The API saves
302when you leave outredirect_status_code. The Sitemap screen’s Redirect Type starts at Permanent (301). -
Exact paths only. A route on
/tv-offerdoesn’t match/tv-offer/extra. -
Targets. A
redirect_urlcan be a path on the storefront, such as/home/products/beet-blend, or an absolute URL. - Query strings are forwarded on the same site only. The request’s query string is added to a target that is a path or an absolute URL on the request’s host. The target’s own parameters are kept, and the request’s value wins when both carry the same key. A target on another host gets no query string.
- Older saved redirects answer first. Some older stores have redirects saved before route redirects existed. They run before any route rule on the same path. If a route on a path doesn’t take effect, check for one with Fluid support.
Create a redirect with the API
A redirect is a theme region rule. Create it with Create a sitemap route, the same operation the Sitemap screen uses. In thetheme_region_rule object, set:
application_theme_id. Creating a rule for a path and region that already has one replaces it, so sending the same request again is safe. To migrate many URLs, send one request per URL.
Attribution
Fluid looks for a rep in a page URL in this order: theshare_guid or username query parameter, the referral query parameter, a rep subdomain, then the first path segment (the second, after /my/). See FairShare SDK and the storefront.
A visit to a member’s credit path establishes that member’s credit, and the member keeps it across later pages and visits. Non-credited routes and redirects establish no new credit, and they don’t remove credit a visitor already has. See FairShare: sales rep attribution.
On a non-credited route the first path segment is the route, so Fluid looks it up as a username. Today that means:
- The route doesn’t establish credit. A shopper who reaches
/spring-salefrom search, an ad, or a backlink without a member’s credit places an order with no rep. A shopper a member already credited keeps that member’s credit. - Credited links to the route break.
/jordan-lee/spring-salereturns404. Members should share the product’s or page’s own credit path, such as/jordan-lee/products/beet-blend. - Usernames and routes collide. Fluid doesn’t stop a route from matching a member’s username, or a username from matching a route. A member named
spring-saleloses/spring-saleto the route, and visits to the route credit that member. - Country routes don’t change credit. The admin offers a Fair Share option on country routes, but it has no effect.
- Keep every link a member shares on a credited path:
/<username>/.... - Redirect marketing and legacy URLs to the product or page, as described in Recommended. Don’t add
?username=to a marketing URL. - Use non-credited routes only for company pages, search landing pages, and legacy URLs that must keep their address.
- Before you create a non-credited route, check that no member uses its first segment as a username.
Migrate a site
- List the old site’s URLs and the Fluid product, page, or collection each one stands for.
- Add a permanent (
301) redirect route for each URL that has a Fluid equivalent, to its/home/...address, such as/home/products/beet-blend. With the API, send one create request per URL. - Use a non-credited route only for a URL that must keep its address and has no Fluid page to redirect to.
- Point members at their credited links. Member links use
/<username>/...paths from the Fluid mobile app or their own storefront, not the old site’s URLs. - Test each old URL on the live domain, including one you’ve already visited, and confirm it reaches the right page.
Sitemap
Custom routes on the active theme appear in/sitemap-custom.xml, linked from /sitemap.xml. A credited route is listed at /home/<path> and a non-credited route at /<path>, the addresses each one answers at. See Sitemap.
API reference
- Sitemap: Get sitemap URLs and Update sitemap URL visibility.
- Custom routes, country routes, and redirects: List, Create, Show, Update, and Delete theme region rules.