Product External Redirect Guide
This guide explains how to set up automatic redirects for products on your Fluid store to corresponding pages on your main website, preserving the affiliate/rep subdomain.
Overview
When a customer visits a product page on the Fluid store, they will be automatically redirected to the corresponding page on your main website with the rep's subdomain preserved.
Example:
- Customer visits: https://yourstore.fluid.app/johndoe/products/product-name-1438
- Redirects to: https://johndoe.yoursite.com/shop/product/SKU-123
The johndoe part of the Fluid URL path becomes the subdomain on your main site.
Step 1: Create a Product Metafield
For each product that needs to redirect, create a metafield containing only the path (not the full URL).
Via Fluid Admin UI
- Navigate to the product in Fluid Admin
- Scroll to the Metafields section
- Add a new metafield:
- Key: redirect_url
- Value: Just the path portion (e.g., /shop/product/SKU-123)
- Type: Single line text
Via Fluid Admin API
POST /api/v2/metafields
Request Body:
{
"resource_type": "product",
"resource_id": "YOUR_PRODUCT_ID",
"namespace": "custom",
"key": "redirect_url",
"value": "/shop/product/SKU-123",
"value_type": "single_line_text_field"
}
Important Notes
- Store only the path, not the full URL
- Path should start with /
- Examples of valid values:
- /shop/product/SKU-123
- /products/product-name
- /collections/category-name
Step 2: Product Template Code
The redirect logic is implemented in product/default/index.liquid.
Working Implementation
{%- assign redirect_path = null -%}
{%- for mf in product.metafields_collection -%}
{%- if mf.key == 'redirect_url' -%}
{%- assign redirect_path = mf.value -%}
{%- endif -%}
{%- endfor -%}
{%- if redirect_path and redirect_path != blank -%}
{%- if affiliate_guid == 'home' or affiliate_guid == blank -%}
{%- assign redirect_url = 'https://www.yoursite.com' | append: redirect_path -%}
{%- else -%}
{%- assign redirect_url = 'https://' | append: affiliate_guid | append: '.yoursite.com' | append: redirect_path -%}
{%- endif -%}
<script>window.location.replace("{{ redirect_url }}");</script>
<noscript>
<meta http-equiv="refresh" content="0;url={{ redirect_url }}">
</noscript>
<style>body { display: none !important; }</style>
{%- else -%}
<main class='product-page-section'>
{% section 'main_product', id: "main_product" %}
{% section 'related_products', id: "related_products" %}
</main>
<script src="{{ 'product.js' | asset_url }}" defer></script>
{% schema %}
{
"sections": {
"main_product": {
"type": "main_product"
},
"related_products": {
"type": "related_products"
}
}
}
{% endschema %}
{%- endif -%}
Note: Replace yoursite.com with your actual domain in both places within the code.
How It Works
Metafield Access
Metafields are accessed via product.metafields_collection, which returns an array of objects:
{{ product.metafields_collection }}
// Output: {"key" => "redirect_url", "value" => "/shop/product/SKU-123"}
To get a specific metafield value, loop through the collection:
{%- for mf in product.metafields_collection -%}
{%- if mf.key == 'redirect_url' -%}
{%- assign redirect_path = mf.value -%}
{%- endif -%}
{%- endfor -%}
URL Transformation
| Fluid Store URL | Redirects To |
|---|---|
| yourstore.fluid.app/johndoe/products/product-name | johndoe.yoursite.com/shop/product/SKU-123 |
| yourstore.fluid.app/janesmith/products/product-name | janesmith.yoursite.com/shop/product/SKU-123 |
| yourstore.fluid.app/home/products/product-name | www.yoursite.com/shop/product/SKU-123 |
Key Variables
| Variable | Description | Example Value |
|---|---|---|
| affiliate_guid | The rep/affiliate credit from the URL path | johndoe, home |
| product.metafields_collection | Array of metafield objects | [{"key": "redirect_url", "value": "/shop/..."}] |
Redirect Behavior
| Component | Purpose |
|---|---|
| window.location.replace() | Redirects without adding to browser history |
| <noscript> fallback | Handles users with JavaScript disabled |
| body { display: none } | Prevents flash of content before redirect |
Testing
- Create a test product with the redirect_url metafield set to /shop/product/test
-
Visit via affiliate URL: https://yourstore.fluid.app/youraffiliate/products/test-product
- Should redirect to: https://youraffiliate.yoursite.com/shop/product/test
-
Visit via home URL: https://yourstore.fluid.app/home/products/test-product
- Should redirect to: https://www.yoursite.com/shop/product/test
- Test back button - Should skip the Fluid product page entirely
Troubleshooting
Redirect not working?
-
Check the metafield exists in Admin UI or via API:
- GET /api/v2/metafields?resource_type=product&resource_id=YOUR_PRODUCT_ID
-
Debug the metafield value - Add this temporarily to the template:
- <div style="background: yellow; padding: 20px;"> <p>metafields_collection: {{ product.metafields_collection }}</p></div>
- Check the path format - Must start with /
- Verify the key name - Must be exactly redirect_url
Wrong subdomain?
- Verify affiliate_guid - Add {{ affiliate_guid }} temporarily to see its value
- Check the URL - Ensure the affiliate credit is in the URL path
Flash of content?
The body { display: none } should prevent this. If still visible:
- Move the style tag to <head> in layouts/theme.liquid
- Ensure no CSS is overriding display property
Quick Reference
Metafield Setup
| Field | Value |
|---|---|
| Key | redirect_url |
| Value | /shop/product/YOUR-SKU |
| Type | Single line text |
URL Pattern
https://{{ affiliate_guid }}.yoursite.com{{ redirect_path }}
Template Variable
product.metafields_collection
Technical Notes
Why metafields_collection?
Fluid has two metafield storage systems:
- Embedded metafields (metafields_collection) - Used by Admin UI and API
- Legacy metafields (metafields table) - Older system
The product.metafields_collection variable accesses embedded metafields created via the Admin UI or API. The older product.metafields syntax reads from the legacy system.
Support
- Metafields API: Fluid API Documentation
- Theme development: Fluid Themes Guide
Comments
Please sign in to leave a comment.