How to Create a Product Page Cross-Sell Widget

A Product Page Cross-Sell widget shows product recommendations on your Shopify product pages, so a shopper looking at one product also sees complementary products they can add to the cart without leaving the page. This guide takes you from an empty widget to a live one: create the widget, connect a Data Source, set the layout, write the copy, install it in your theme, and turn on Live Mode.

Product Cross-Sell is the widget type name you will see in the Rebuy widget editor top bar, and it is the type behind every standard product page recommendation widget. A cross-sell adds the recommended product alongside what the shopper is already buying, so the cart ends up with both. It never swaps out the product they were looking at.

Rebuy has four widget types that all appear on the product page, and they differ in how the shopper adds the products and in what happens to the cart. Pick the type before you start building, because the type is set at creation and cannot be changed afterward. The table below matches each goal to its widget type, then gives the shopper's add action and the result in the cart.

For an upsell build, see How To Create A Product Upsell Widget. For add-ons, see Create A Product Add-Ons Widget. For the full catalog of every Rebuy widget type, see Rebuy Widget Types.

This guide covers the embedded display style, which sits inline in the product page. If you want the recommendations to appear as a pop-up overlay when the shopper clicks Add to Cart, build the same widget type with Display Type set to Popup and follow How To Create A Product Cross Sell Pop Up Widget instead.

You create the widget from the Rebuy Widgets page by picking one of the Product Page starting configurations. Each configuration is a preset that fills in the endpoint and the default copy for you, and several of them create the same Product Cross-Sell widget type with different presets.

The widget's Data Source decides which products it recommends and whether the widget appears at all. A Product Cross-Sell widget renders whenever its Data Source returns at least one product, and hides itself when the rules return nothing, so the rules are your visibility control as well as your merchandising control.

A widget created from the AI Recommendations configuration returns AI-driven recommendations based on the product being viewed, with no rules written at all. You only need rules when you want to control what appears in specific situations, such as returning Top Sellers for a product with no purchase history, or featuring one collection during a promotion. For the full rule reference, see Data Sources 101.

On a Product Cross-Sell widget, the input product is the product whose page the shopper is viewing. That single fact drives two behaviors worth knowing before you write rules.

Cart Rules are available on a Product Cross-Sell widget's Data Source and they do evaluate: Rebuy sends the shopper's cart with every widget request, whatever the widget type. A rule on cart subtotal, line item count, total item count, a specific product in the cart, or an applied discount code will match correctly on a product page widget.

What differs from a cart widget is timing. A Product Cross-Sell widget requests its products once, when the product page loads, so a Cart Rule is evaluated against the cart as it stood at that moment. The widget does not re-request when the shopper adds or removes items, so it cannot start or stop matching partway through the page visit. A cart cross-sell widget re-requests on every cart change, which is why an offer that has to react to the cart in real time belongs in the cart rather than on the product page. See How to Create an Embedded Cart Cross-Sell Widget for that build.

The Screens section of Widget Settings decides how the widget's products are laid out, and how many of them are on screen at one time on each device. It does not decide how many products the widget has to work with. That is Max Number of Products displayed, in the DATA SOURCE section from Step 2, and it is the setting that controls how many products the widget renders at all.

Treat the two as a request and a window. Max Number of Products displayed sets how many products the widget requests, up to 20. The Screens settings then decide how many of those the shopper sees at once, and whether the rest are reachable through carousel arrows or wrapped onto additional rows. Max Number of Products displayed is the ceiling on both: no layout setting can put more products on the page than the widget requested.

Screens holds one card per screen size, and each card has its own independent copy of every setting.

Changing Large Screen does nothing to how the widget looks on a phone, so configure all three whenever you change one. Each card holds the four settings in the table below.

Grid Columns and Carousel decide how many of the requested products are on screen at once. With Carousel on, Grid Columns is how many products are visible at one time, and the rest are reached with the arrows. With Carousel off, Grid Columns is how many products sit per row, and every product the widget requested renders, wrapping onto as many rows as it needs.

Worked example: Max Number of Products displayed is 8, and Large Screen is set to 4 columns with Carousel on. A desktop shopper sees 4 products, with the other 4 behind the carousel arrows. To show all 8 at once on desktop, either raise Grid Columns to 6 and accept a second row of 2, or turn Carousel off so the products wrap.

The Language tab holds every piece of text the widget displays, and the heading is what shoppers read as the section title on your product page. A new widget inherits its heading from the starting configuration you picked, so a widget created from AI Recommendations opens with "You may also like".

A Product Cross-Sell widget renders where you place it in your Shopify theme, so it does nothing until it is installed. Which method you use depends on your theme version, and the widget editor generates the exact code either way.

If the widget renders in the wrong spot, you can reposition it without editing your theme's code. There are two ways to do it, and on a 2.0 theme the first one is the one to reach for.

Drag the app block in Shopify's theme editor. This is the recommended method, because it needs no code at all. Your widget is an app block, so you move it the way you move any other block: in Shopify, go to Online Store > Themes > Customize, select your product template, find the Rebuy Widget block in the section list, and drag it up or down to where you want the recommendations to appear. Save the theme. Use this whenever the position you want is somewhere the block can actually be dragged to.

Use Dynamic Placement in the widget editor. Reach for this when dragging cannot get you there: the spot you want sits inside another section, or your theme is a vintage (1.0) theme with no app block to drag, or you need the widget in a different position on mobile than on desktop. In the widget editor, open Advanced > Dynamic Placement, then set two fields per screen size:

Because this method needs a CSS selector read off your own storefront, it is the more technical of the two, and a selector that your theme later renames will silently stop working. For help finding the right selector, see Dynamic Placement Selectors.

Testing before shoppers see the widget is the reason to turn Live Mode off in Step 1. Once the widget is installed and you are happy with it, Live Mode is what makes it public.

If the widget does not appear at this point, work through the FAQ below before anything else, then see Why Isn't My Widget Showing?.

You can attach a discount to a Product Cross-Sell widget so its recommended products display at a reduced price. Making the discount actually apply at checkout takes one setting beyond the amount itself.

The widget editor shows the same tabs for every widget type, and most of them are shared. The settings below are the ones that change how a Product Cross-Sell widget behaves on a product page.

The following constraints apply to Product Cross-Sell widgets on the product page. Each has a workaround or an alternative where one exists.

The Styles tab gives you two ways to change how the widget looks, and one of them needs no code.

Set Theme to Custom for colors and button shape. Open the Styles tab and you will see a Theme selector with no styling fields under it. Switch Theme to Custom and the tab reveals a group of color pickers, plus two number fields for button geometry, covering most of what merchants want to change. Nothing here requires CSS.

Use the CSS box for everything else. The CSS box sits in the same tab and stays available. Use it when the fields above cannot get you there, which in practice means spacing, font sizes and font families, hover states, and hiding an element. There are no spacing or typography fields in the Custom theme, so any type or layout change is a CSS change.

For ready-to-use snippets aimed at this widget, including product images, titles, prices and the Add to Cart button, see the Product Page Recommendation Widget CSS Styling Guide.

Advanced > Callbacks runs your own JavaScript at specific points in the widget's lifecycle, which is how you reach behavior no setting exposes. The admin lists one section per event, each with an enable checkbox and its own code editor, and the editor only becomes editable once you enable that event.

These are the events most common for JS customizations on a product page widget:

Custom JavaScript falls outside standard Rebuy support, as custom CSS and custom templates do. For what the widget instance exposes, see Widget Settings and Widget Methods in Rebuy's developer documentation. Rebuy's Partner team can connect you with an agency if you do not have a developer.

When a Product Cross-Sell widget displays fewer products than you configured, the products are usually being returned correctly and the layout is showing only some of them at a time. Check these three things in this order:

The products are not lost in any of these cases. They are returned by the Data Source and present in the widget, and the layout is deciding how many sit on screen at once.

No, a Product Cross-Sell widget cannot change its recommendations based on the selected variant. The widget's input is the product, so its Data Source evaluates once when the page loads and does not re-run when the shopper switches variant. The Match On Variant setting matches variant options between the viewed product and the recommended products, but it does not make the rules re-evaluate.

The workaround is one rule pair per case: an IF rule naming the specific product, and a RETURN rule naming the specific variant to recommend. That has to be built product by product, so it suits a small catalog rather than a large one. If the offer can wait until the item is in the cart, a cart cross-sell widget does see the exact variant that was added.

No, you cannot use one widget ID twice on the same page. Rebuy renders one instance per widget ID and removes the extra placements from the page entirely, keeping the first one in the page's document order. The removal is silent and the removed placement is not listed in Preview Mode.

To show the same recommendations in two places:

Both widgets can stay connected to the same Data Source, so the recommendations stay consistent while each placement keeps its own layout and settings.

A Product Cross-Sell widget that never appears is almost always one of the following, in this order of likelihood:

For broader troubleshooting, see Why Isn't My Widget Showing?.

A cross-sell and an upsell differ in what happens to the product the shopper was already buying. A cross-sell adds the recommended product alongside it, so the cart ends up with both. An upsell replaces it with the recommended product, so the cart ends up with only the upsold one. A Product Cross-Sell widget always adds. To replace, build a Product Upsell widget instead: see How To Create A Product Upsell Widget.

Yes, and the right tool depends on what you want to change. For colors and button shape, set Theme to Custom on the widget's Styles tab and use the fields it reveals, with no code involved. For spacing, typography and sizing, which have no fields, use the CSS box on the same tab, scoped to the widget ID. The Product Page Recommendation Widget CSS Styling Guide has snippets for each part of the layout. For structural changes, meaning different markup, extra elements, or rearranged product information, a developer can replace the widget's template entirely: see Widget Custom Templates. Custom CSS and custom templates fall outside standard Rebuy support, and Rebuy's Partner team can connect you with an agency if you do not have a developer.