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.

Variants in Variant Metafield returns the product tied to a variant you've referenced using a list.variant_reference metafield attached to your product's variants in Shopify. Rebuy reads the referenced variant IDs off the current product's variants, resolves each to its parent product, and returns only the referenced variant(s), not the full product. Setup for this rule type is covered in the Variants in Variant Metafield Data Source Rule section below.

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.

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."

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

Define your Data Source rule using the exact metafield namespace.key (for example, custom.color_name).

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.

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]

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.

[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]

[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]

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

[IMAGE example above: Rebuy Data Source editor showing the full rule using RETURN Products In Metafield → custom.complete_the_look]

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.

The Variants in Variant Metafield rule returns the product tied to a specific variant you've referenced on the input product using a list.variant_reference metafield in Shopify. Unlike Products in Metafield, which references whole products, this rule references individual variants, useful when the relationship you're modeling is variant-specific rather than product-wide.

When the rule fires, Rebuy reads the list.variant_reference metafield from the variants of the current product (the product matched by your IF condition), resolves each referenced variant to its parent product, and returns those products. The response includes only the variant(s) that were actually referenced, not the full variants array of the returned product.

After populating metafield values, clear the Collections, Metafields, Presentment Prices Cache in Rebuy Admin to ensure Rebuy picks up the new variant reference data. Go to Rebuy Admin → Data Sources → Cache Manager. See article Sync Product Data, Store Data, and Clear Cache.

Variant-specific pairing: Reference the exact matching variant of a companion product, for example a specific mug color that pairs with a specific shirt color, rather than pairing at the product level where any color combination would show.

Curated cross-sell down to size or color: Recommend a specific complementary variant (a matching lens color, a specific replacement part SKU) instead of leaving the shopper to find the right one among a full product's variants.

Editorial control at the SKU level: Specify exactly which variant appears alongside a given variant, overriding AI recommendations for cases where the relationship is too specific for a shared attribute or tag to capture.

Gift-with-purchase by variant: A skincare brand wants a specific sample-size variant of its face oil to appear as a gift-with-purchase item when a customer has a qualifying product, such as a moisturizer, in their cart. The face oil's sample variant is referenced in a list.variant_reference metafield, and the IF condition matches on the moisturizer being present in the cart. The RETURN resolves to the sample variant specifically, not the full-size face oil product.

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.

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.

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.

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.

Yes, on the RETURN side. The Variants in Variant Metafield rule reads a list.variant_reference metafield from the input product's variants and returns the specific referenced variant(s). Data Source "IF" conditions on metafields are evaluated at the product level, so Product Has Metafield doesn't support variant-level values.