Before you begin
- Create Shopify metafields that store product, variant, collection, or list references.
- Give each metafield Storefront access in Shopify. Definitions with Storefront access set to None do not appear.
- Put values on the product or variant that customers add to the cart.
- You can select up to 5 metafields in one module.
When to use it
Use Metafields when product relationships already live in your catalog, instead of broad rules.
- A product metafield points to matching accessories for every variant of that product.
- A variant metafield points to a compatible refill or replacement part for one selected SKU.
- A collection reference metafield points to a related set of products.
- Your merchandising team already maintains these relationships in Shopify.
Product metafields and variant metafields
The picker has two sections: Product metafields and Variant metafields.
Owner | Where the metafield lives | What Order Editing reads |
|---|---|---|
Product | The product in Shopify | The cart product. Every variant of that product shares the same related products. |
Variant | The variant in Shopify | The selected cart variant only. Sibling variants can point at different related products. |
Owner is not the same as type. Type is what the metafield points at: a product, a variant, a collection, or a list of those.
The same namespace and key can exist twice, once on the product and once on the variant. Select the row that matches where you stored the value. Each selected row shows a Product or Variant badge.
Set up the module
- Open Apps > Order Editing > Upsells and create or edit a strategy.
- Go to WHAT and select Add Module.
- Select Metafields. The Select metafields picker opens.
- Choose a metafield from Product metafields or Variant metafields.
- Select Add if you need another metafield, up to 5.
- If you selected a collection reference, set Max products per collection.
- Set Recommended quantity.
- Write the offer text.
- Select Save.
Product metafields read the cart product. Variant metafields read the selected variant.
Configuration options
Option | What it controls | Recommended approach |
|---|---|---|
Selected metafields | Which product-owned or variant-owned references are used | Choose metafields your team maintains, and match the owner to where the value lives |
Max products per collection | How many products to pull from each collection reference (1 to 20) | Keep this low so the relationship stays specific |
Product filters | Limits returned metafield products | Use filters as guardrails, not as the main logic |
Recommended quantity | How many units the offer suggests | Match the typical add-on quantity |
Offer text | The message shown with referenced products | Explain the relationship, such as compatibility or refill fit |
How to structure the data
Use product or variant reference metafields for exact recommendations. Use collection reference metafields when each source should point to a small curated collection.
Keep the number of referenced products small. The more precise the relationship, the better the offer feels.
If your team will not maintain metafield values, use a Collection module or Keyword Search instead. Empty metafields create empty recommendations.
Catalog setup | Recommended use |
|---|---|
Product-owned product reference | One or more related products for every variant of the purchased product |
Variant-owned product reference | SKU-specific compatibility, such as a refill that matches only that variant |
Variant reference | A specific compatible variant, such as a matching part |
Collection reference | A curated collection tied to the product or variant |
Preview the offer
- Open the strategy preview.
- Confirm the referenced products appear for a cart line that has values in the selected metafields.
- For a variant-owned metafield, preview two variants of the same product when they should recommend different products.
- For Checkout Page placement, add a matching product to the cart and continue to checkout. You do not need to place an order.
Troubleshooting
No metafields are available
Check that the Shopify definitions use supported reference types: product, variant, collection, or a list of those. Text-only metafields are not enough.
Check Storefront access. Definitions set to None do not appear.
No products appear
For a Product badge, check that the purchased product has a value.
For a Variant badge, check that the selected cart variant has a value. A product-level value is not used.
Empty metafields do not produce recommendations.
The wrong related product appears
Confirm you selected the row under Product metafields or Variant metafields that matches where you stored the value. The same namespace and key on the product and on the variant are different selections.
Too many collection products appear
Lower Max products per collection.
