Custom upsell promotion

Pair products individually with different product

Story can be customized to match any product with another when using metafields. This allows you to customize which product is displayed as the upsell promotion on each individual product page.

Unique promotions for each product

Pair products with specific products to display custom upsell promotions:

How to configure

There are three initial steps involved when setting up custom paired products:

  1. Create an upsell product reference metafield called theme.upsell

  2. Go to each product that should have an upsell and select the product you want to upsell

  3. Connect the metafield in the Theme Editor using the "upsell" block on the product form

After the initial setup, each product can easily be paired with other products using your Shopify Admin under Product setup.

Quick setup for experienced users

The most important part of setting up this metafield is to use the namespace and key of:


See the examples here (click on images to zoom):

The Content type must also be "Reference" and choose "Product".


  • The namespace begins with theme. Example: theme.upsell. This custom namespace allows Story to display a custom promotion.

  • The metafield type is Reference -> Product

See below for detailed animations.

Full detailed step-by-step setup

The first step is to define a custom metafield that Story theme supports.

Start in your Shopify Admin -> Settings and choose Metafields from the left panel and then click on Products (click images to zoom):


  • Click the Add definition button

  • type-in "upsell" for the Name

  • Change the Namespace and key from my_fields to theme. The namespace and key should now be: theme.upsell

Use the Select content type button and choose Reference and then Product:

Use the Save button to finish.

Your upsell metafield is now complete and ready to use.

Product setup

Now that our custom metafield has been defined, we can easily associate another product as our upsell product.

The next step is performed in the Shopify Admin -> Products. Choose a product and scroll to the bottom where you'll find all the metafields. There will be a new upsell option where you can pick another product to pair with:

Story will use the chosen product to create an upsell promotion for the product page and the cart drawer or popup cart.

Configure upsell block

The final step is to configure the upsell block in the Theme Editor for the current product template. Be sure to add the Upsell block under Product page.

Next, click on the Connect dynamic source icon and choose the upsell metafield we created earlier as your source:

This step is only required once for the current product template. If you have multiple product templates, connect to the upsell source for each template.

All steps are complete, you can now pair any of your products with unique products. These will appear as upsell promotions on product pages and in the cart drawer or popup cart.

Last updated