Overview
Cross-sells appear as a slim list of complementary products on the product detail page. Customers can add them in a single click, and each row’s frequency stays in lock-step with whatever subscription plan the customer picks for the main product. Accessories and one-shot extras can be marked to always sell as a one-time purchase, even when the main product is on a subscription.Configuring cross-sells in the app
Cross-sell relationships are configured directly inside the circuly Subscriptions app — no metafield editing required.1
Open the Cross-sell page
In the app, open Cross-sell from the navigation. You’ll see a list of products and how many cross-sells each one has configured.
2
Pick a main product
Click the product you want to add cross-sell recommendations to. This is the product whose page on the storefront will show the cross-sell rows.
3
Add eligible products
Click Add products. The picker shows products that share at least one selling plan group with the main product — they’re the ones that can mirror the main product’s plan. Pick the cross-sells you want, up to 12 per main product.
4
Set the purchase mode per row
Each row has a Purchase mode dropdown:
- Match main product — the cross-sell follows whatever plan the customer picks for the main product. If the customer is on a one-time purchase, the cross-sell is added one-time too.
- One time — the cross-sell is always added as a one-time purchase, even when the main product is on a subscription. Use this for accessories or starter kits that shouldn’t recur.
5
Save
Click Save changes. The Banner above the table is also a quick reference for the two modes.
Behind the scenes, the app stores the relationship in two product metafields on the main product:
custom.cross_sell_products (the full list) and custom.cross_sell_one_time_products (the subset forced to one-time). You shouldn’t need to edit these directly — the app keeps them in sync — but they’re documented here in case you’re inspecting the storefront via Liquid.How frequency mirroring works
The storefront block strictly reacts to the main product’s selection so the cart never holds a stale plan.
If the customer changes the main product’s plan group while a cross-sell is selected, the cross-sell is automatically deselected and removed from the cart. The customer can re-add it under the new context with the right plan attached.
Storefront block
The storefront rows are rendered by the Cross-sell Products theme app block. Adding it to your theme is a one-time setup.1
Open the Theme Editor
In your Shopify admin, go to Online Store > Themes, then Customize on your active theme.
2
Switch to a product page
Use the page selector at the top to switch to a Product page template.
3
Add the block
In the section sidebar, click Add block under the product section. Find Cross-sell Products under the Apps section and select it.
4
Position it
Drag the block somewhere visible on the product page — typically below the price/buy buttons or below the product description.
5
Save
Click Save in the top right.
Block settings
Eligibility rules
- A product is eligible to be a cross-sell only if it shares a selling plan group with the main product. The picker in the admin enforces this.
- The main product must have at least one selling plan group for cross-sells to mirror; without plans, only One time mode is available.
- Cross-sells must be available (published, in stock) at render time. Unavailable products are silently skipped on the storefront.
- The list is capped at 12 cross-sells per main product.