Skip to main content
Fluid gives a storefront two ways to answer a URL that isn’t one of its built-in supported paths:
  • 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.
Merchants manage both on the Sitemap screen, including redirects. Both are stored as theme region rules. See API reference.
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.
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:
Make it a non-credited custom route whose 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 301 or 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

A redirect rule sends its redirect_status_code, 301 or 302, to the rule’s redirect_url:
  • Status. The API saves 302 when you leave out redirect_status_code. The Sitemap screen’s Redirect Type starts at Permanent (301).
  • Exact paths only. A route on /tv-offer doesn’t match /tv-offer/extra.
  • Targets. A redirect_url can 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 the theme_region_rule object, set:
The rule goes on the company’s active theme unless you send 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: 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 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.
  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. 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