Documentation Index
Fetch the complete documentation index at: https://app.docs.circuly.io/llms.txt
Use this file to discover all available pages before exploring further.
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.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.
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.
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.
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.
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.| Main product state | What the customer sees |
|---|---|
| Subscription plan group A selected | Only cross-sells that share group A are visible. Their displayed price is the plan-allocation price (subscription-discounted). Adding them attaches the same plan id. |
| One-time purchase (or no plan selected yet) | All cross-sells are visible at base price. Adding them creates one-time line items. |
| Force-one-time cross-sell | Always visible regardless of the main product’s state. Always added as one-time at base price. |
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.Open the Theme Editor
In your Shopify admin, go to Online Store > Themes, then Customize on your active theme.
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.
Position it
Drag the block somewhere visible on the product page — typically below the price/buy buttons or below the product description.
Block settings
| Setting | Description | Default |
|---|---|---|
| Show heading | Display a heading above the rows | On |
| Heading text | The heading text | ”Complete your order” |
| Show prices | Display prices on each row | On |
| Click-to-add | When on, clicking a row adds it to cart immediately and selected rows can be deselected by clicking again. When off, each row gets an Add to cart button | On |
| Add to cart button | Label for the per-row button when click-to-add is off | ”Add to cart” |
| Primary color | Accent color for the selected ring and check chip | #397971 |
| Top margin | Spacing above the block (0–100px) | 32px |
| Bottom margin | Spacing below the block (0–100px) | 32px |
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.