Skip to main content
Fluid gives a storefront three ways to answer a URL that isn’t one of its built-in supported paths:
  • Redirects send an exact path to another address with a permanent 301.
  • Custom routes serve a template, a resource, or a temporary 302 redirect at a path you choose.
  • Country routes change what a route serves for visitors from particular countries. They work on custom routes and on built-in pages.
Merchants manage them in the admin on the Sitemap and URL Redirects screens. Custom and country routes are stored as theme region rules. See API reference. 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:
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 the redirect type by what the URL needs: Redirects on the URL Redirects screen have one target for every visitor. Only country routes can send visitors from different countries to different places.

​
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 302 to the rule’s URL.
  • Nothing (disabled). A 404 for visitors from the rule’s countries. A disabled rule can’t be the default rule.
When a route serves content, Fluid renders it in place. The visitor’s address bar keeps the route’s URL, such as /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:
  1. The region query parameter, such as ?region=CA. Use it to test; don’t put it in links you publish.
  2. The country in the visitor’s saved locale, which the locale selector sets, such as CA in fr_CA.
  3. The visitor’s location, from the CDN’s geolocation headers.
  4. The company’s default country.
  5. US.

​
Rule selection

For a route, Fluid then picks one active rule on the active theme:
  1. A rule for the visitor’s country.
  2. The route’s default rule. Only custom routes have one.
  3. A rule for the company’s default country.
Within a tier, the rule with the lower priority number wins.

​
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

Redirects on the URL Redirects screen run before any route:
  1. Redirects. An exact path match sends a 301 to the target. A redirect can be limited to one domain through the API; otherwise it applies on every storefront domain.
  2. Custom and country routes. If no redirect matched, Fluid applies the route’s rule.
  3. The built-in page, if no rule applies.
Things to know:
  • Exact paths only. A redirect on /tv-offer doesn’t match /tv-offer/extra.
  • Query strings aren’t forwarded. Neither redirects nor 302 route rules carry the request’s query string to the target.
  • Usernames win. A redirect on a single-segment path, such as /jordan-lee, doesn’t fire while an active member has that username.
  • Some paths can’t be redirected. A path that contains /app, /www, /fluid, /api, /shop, /cable, /cart/, /checkout/, or /admin/ anywhere is rejected, so /apple-cider and /shop-sale are too. So is a path that matches a built-in route, such as /:credit/products/:slug.
  • Changes can be slow. Redirect lookups are cached per path and domain for up to 30 days, and saving a redirect doesn’t always clear that cache today. Create a redirect before you publish the URL.

​
Attribution

Fluid looks for a rep in a page URL in this order: the share_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-sale from 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-sale returns 404. 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-sale loses /spring-sale to 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.
To keep members’ links working:
  • 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

  1. List the old site’s URLs and the Fluid product, page, or collection each one stands for.
  2. Add a redirect for each URL that has a Fluid equivalent, to its /home/... address, such as /home/products/beet-blend.
  3. Use a non-credited route only for a URL that must keep its address and has no Fluid page to redirect to.
  4. 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.
  5. 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. The sitemap currently lists a credited custom route at /<path> rather than /home/<path>, so prefer a redirect or a non-credited route for a URL that must be indexed. See Sitemap.

​
API reference