Overview
Cross-sells appear as a slim list of complementary products inside the Unified purchase selector, under the add-to-cart button. Customers add one by ticking its row, 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 cross-sell list 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 (or switches between subscription and one-time) 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.
On the storefront
Cross-sells show up automatically in the Unified purchase selector block on the main product’s page. There is no separate block to add. If the product has no available cross-sells, the list doesn’t render. The selector’s Cross-sell settings (at the bottom of the block’s settings in the Theme Editor) control the list:
The list uses the selector’s own colors, corner radius and text size.
Cross-sells used to have their own Cross-sell Products block. It has been retired: the list now lives inside the Unified purchase selector, which already knows the customer’s plan.
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.