Metafields are a powerful tool for customizing product relationships and recommendations in Rebuy. They allow you to add specific, custom data to your products and set up rules that deliver personalized experiences to your customers. This guide explains how to configure metafields, set up data sources, and utilize them to optimize your product recommendations.
How Metafields Work in Rebuy
Rebuy Data Sources support two distinct metafield rule types. Understanding the difference between them matters because they work differently and serve different use cases.
Value Matching returns products that share the same metafield value as the product being viewed. For example, a rule using custom.color_name returns all products where custom.color_name equals the same value (such as "Red"). Products are grouped by a shared attribute across your catalog. Setup for this rule type is covered in the Metafield Value Matching Rules section below.
Products in Metafield returns specific products you have manually assigned to each product using a list.product_reference metafield in Shopify. Rebuy reads the product references stored on the current product and returns exactly those products, giving you direct editorial control over what appears per product. Setup for this rule type is covered in the Products in Metafield Data Source Rule section below.
Note: Metafield Data Source rules operate at the product level only. Variant-level metafield values are not currently supported.
Value Matching Metafield Data Source Rules
The Value Matching metafield rule types returns products that share the same metafield value as the product a customer is currently viewing. Both the current product and the returned products must have the same metafield defined with the same value.
Product Has Metafield: Use the "Product Has Metafield" condition and specify the metafield namespace.key you want to match
Products with Matching Metafields: Set the RETURN to "Products with Matching Metafields" and enter the namespace.key of the metafield to match on.
How Metafield Value Matching Works
When the rule fires, Rebuy reads the specified metafield on the current product and returns all products in your catalog that share the same value for that metafield.
For example: if you configure a rule using custom.color_name and the current product has custom.color_name = "Red", Rebuy returns all other products where custom.color_name is also "Red."
Steps to Set Up Value Matching in Shopify
Step 1: Define the metafield
Navigate to Settings → Metafields and metaobjects → Products → Add definition in Shopify.
Name the metafield and note the namespace.key it generates (for example,
custom.color_name).
Step 2: Add the metafield to products
Go to Products in the main menu and select a product you want to configure.
Scroll down to the Metafields section at the bottom of the product page.
Locate the metafield you created and enter its value (for example, "Bedroom" for
custom.home.room).Repeat for every product that should be grouped together under that value.
Step 3: Sync with Rebuy
Once you have applied the metafield to your products, go to Rebuy Admin and perform a re-sync to update Rebuy with your changes. Allow some time for the sync process to complete. See article Sync Product Data, Store Data, and Clear Cache
Step 4: Set up the rule in Rebuy
Define your Data Source rule using the exact metafield namespace.key (for example, custom.color_name).
Configuring the Value Matching Rule in the Rebuy Data Source Editor
Product Has Metafield: Use the "Product Has Metafield" condition and specify the metafield namespace.key you want to match (for example,
custom.color_nameorcustom.clothing_color).
[IMAGE example above: Rebuy Data Source editor showing IF: Product Has Metafield → Equals → custom.clothing_color]
Products with Matching Metafields: Set the RETURN to "Products with Matching Metafields" and enter the namespace.key of the metafield to match on. This returns products where the metafield value matches the current product's value.
[IMAGE example above: Rebuy Data Source editor showing RETURN: Products with Matching Metafields →
custom.clothing_color, with arrow pointing to the namespace.key field]
Metafield Value Matching Use Cases
1. Matching Colors
Use a metafield like custom.color_name to categorize products by color. If a customer is viewing a red t-shirt, Rebuy recommends other products with custom.color_name = "Red".
2. Pairing Products
Create a metafield like custom.pair_it_with and assign it a shared value for products meant to be sold together. For example, both a wine glass and a wine bottle could have custom.pair_it_with = "Wine Set", allowing them to be recommended together.
Products in Metafield Data Source Rule
The Products in Metafield rule returns specific products you have manually assigned to each product using a list.product_reference metafield in Shopify. Unlike Value Matching, which groups products by shared values automatically, the Products in Metafield rule returns exactly the products you hand-selected per product.
[IMAGE example above: Black Shirt product page showing the "Complete the Look" add-ons widget with Black Belt, Black Pants, and Black Shoes returned via a Products in Metafield rule]
How Products in Metafield Works
When the rule fires, Rebuy reads the list.product_reference metafield from the current product, resolves the stored product references, and returns those products as the recommendation set. The output is entirely determined by what you assigned in Shopify, not by computed matching or AI.
Important: Although Products in Metafield is a Return rule, it depends entirely on the input product — the product matched by your IF condition — having its metafield values configured in Shopify's product settings. If the metafield is empty or not set on that product in Shopify, Rebuy has no product references to resolve and the widget will output nothing. Every product you intend to use as an input must have the metafield populated in Shopify before the rule can return any results.
Setting Up the Products in Metafield Data Source Rule
Step 1: Create the metafield definition in Shopify
In Shopify Admin, go to Settings → Metafields and metaobjects → Products.
Select Add definition.
Name the metafield (for example, "Complete the look").
Set the type to List, then select Product as the content type.
Under Options, enable Storefront API access. This is required for Rebuy to read the metafield values at query time.
Save the definition. Note the namespace.key (for example,
custom.complete_the_look).
[IMAGE example above: Shopify Settings showing the Add product metafield definition screen with name "Complete the look", namespace.key custom.complete_the_look, type List > Product, and Storefront API access toggled on]
Step 2: Populate the metafield on each product
In Shopify Admin, open a product.
Scroll to the Product metafields section at the bottom of the product page.
Locate your metafield and select Select products.
Choose the products you want to recommend alongside this product.
Save the product.
Repeat for every product where you want curated recommendations.
[IMAGE example above: Shopify product page showing the "Complete the look" Product (List) metafield with Black Belt, Black Pants, Black Shirt, Black Shoes, and Black Socks selected]
Step 3: Sync with Rebuy
After populating metafield values, clear the Collections, Metafields, Presentment Prices Cache in Rebuy Admin to ensure Rebuy picks up the new product reference data. Go to Rebuy Admin → Data Sources → Cache Manager.
See article Sync Product Data, Store Data, and Clear Cache
Step 4: Configure the rule in Rebuy
In the Rebuy Data Source editor, add a rule.
Set the IF condition to match the products you want this rule to apply to. This can be a collection, tag, or any other product condition (for example, Collection → clothes → Contains Any).
Set the RETURN statement to Products In Metafield.
In the dropdown, select the metafield you created. The dropdown is populated from your store's available metafields.
Save the Data Source.
[IMAGE example above: Rebuy Data Source editor showing the full rule using RETURN Products In Metafield → custom.complete_the_look]
Products in Metafield Use Cases
Complete the Look: A dress product's metafield lists the matching shoes, bag, and belt. Every visitor on that product page sees exactly those accessories, with no reliance on shared tags or AI.
Hand-picked cross-sells: Curate specific pairings for products where the relationship doesn't map to a shared attribute.
Editorial control for hero SKUs: Specify exactly what appears alongside your most important products, overriding AI recommendations.
Manually defined product relationships: Pair products that share a use case but no common attribute, such as a coffee maker and a specific compatible filter.
Products in Metafield Limitations
Only works with Shopify's native
list.product_referencemetafield type (List > Product). Text, integer, and other metafield types are not supported.Each product's metafield must be populated manually in Shopify's product settings. For large catalogs, a bulk import tool such as Matrixify can populate values at scale.
Storefront API access must be enabled on the metafield definition in Shopify. Without it, Rebuy cannot read the metafield values.
Products referenced in the metafield must be synced to Rebuy to appear in results. A cache clear may be required after adding new values.
Standard product status filtering (Draft, Archived, Unlisted) still applies to referenced products.
If the metafield is not populated on a product in Shopify, the widget rule will not output any products.
Metafield Data Source rules operate at the product level only. Variant-level metafield values are not currently supported.
Tips for Effective Use of Metafields
Minimize rule complexity: Use metafields to group products efficiently, reducing the need for multiple individual rules.
Strategic value assignments: Assign metafield values based on logical groupings like color, category, or complementary use cases.
Choose descriptive values: Use intuitive and meaningful metafield values (for example, "holiday-set") to clearly define product groupings.
Plan your metafield structures: Develop a metafield strategy ahead of time to maintain consistency and align with your data management goals.
Use an AI fallback: Add an AI endpoint (such as Recommended AI) as the last rule in any Data Source that uses metafield rules. If the metafield is empty or unpopulated on a product, the AI rule ensures the widget always returns products.
Verify in Rebuy: Regularly check metafield value accuracy within Rebuy's admin interface to confirm metafield types and values are set up correctly.
Frequently Asked Questions About Metafield Data Source Rules
This section covers common questions and issues merchants encounter when configuring metafield rules in Rebuy Data Sources. Each answer addresses a specific behavior or setup challenge that affects how metafield rules return and display products.
Why are products not being recommended as expected?
Metafield rules in Rebuy return no results when the namespace.key in the rule does not match the metafield definition in Shopify exactly, or when the metafield values are not yet synced to Rebuy. Confirm the namespace.key matches, then clear the Collections, Metafields, Presentment Prices Cache in Rebuy Admin and reload the widget preview. For Products in Metafield, also verify the correct products are selected on the product page in Shopify.
Why is only one product being recommended with the Value Matching rule?
The Value Matching rule only returns products that share the same metafield value as the current product. If only one product is appearing, the metafield value on that product may be unique to it. Use a value that is shared across multiple products (for example, custom.color_name = "Red" assigned to several products). Avoid unique metafield values that don't group products effectively.
Why is my Products in Metafield rule returning no results?
The Products in Metafield rule returns nothing when the input product — the product matched by the IF condition — does not have the metafield populated in Shopify's product settings. Rebuy has no product references to resolve, so the widget outputs nothing. Open the product in Shopify Admin, scroll to Product metafields, and confirm the metafield has products selected. Also verify that Storefront API access is enabled on the metafield definition. After making changes, clear the Collections, Metafields, Presentment Prices Cache in Rebuy Admin.
Do metafield Data Source rules support variant-level metafield values?
Metafield Data Source rules in Rebuy operate at the product level only. Variant-level metafield values are not currently supported for either the Value Matching rules or the Products in Metafield rule.