> ## 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.
# Cross-sell
> Recommend complementary products on the product page that follow the customer’s selected subscription plan
## 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.
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.
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.
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.
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.
Products without selling plans are locked to **One time**.
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.
| 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. |
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.
The price next to each row is what will actually be charged — base price for one-time, plan-allocation price for subscription. The leading **+** shows it’s an add-on cost on top of the main product.
## 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.
In your Shopify admin, go to **Online Store > Themes**, then **Customize** on your active theme.
Use the page selector at the top to switch to a **Product page** template.
In the section sidebar, click **Add block** under the product section. Find **Cross-sell Products** under the **Apps** section and select it.
Drag the block somewhere visible on the product page — typically below the price/buy buttons or below the product description.
Click **Save** in the top right.
### 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**.
## Compatibility with widget layouts
The cross-sell block reads the main product’s currently selected plan from the **Unified purchase selector** block (both the classic and tabbed widget layouts). If you’re using a custom theme that doesn’t use the circuly Unified purchase selector block, the mirroring logic will fall back to one-time for everything.