> ## 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.
# Theme Extension Setup
> Add subscription widgets and cross-sell recommendations to your storefront
## Overview
The circuly Subscriptions theme extension adds three blocks to your Shopify storefront:
* **Unified purchase selector** — A subscription widget on product pages that lets customers choose between subscription plans, one-time purchase, rentals, and bundles
* **Cross-sell Products** — A slim list of complementary products that mirrors the main product’s selected plan. Configured in the app rather than the theme; see the dedicated [Cross-sell page](/docs/mintlify/cross-sell)
* **Bundle progress** — A cart-side counter that shows how many bundle slots are left while the customer shops. Used together with [Bundles](/docs/mintlify/create-bundles)
All blocks are added through the Shopify Theme Editor and require no coding.
## Unified purchase selector block
The Unified purchase selector block displays your subscription plans on the product detail page. When a product has subscription plans assigned, customers see their options with pricing, frequency, and any applicable discounts.
### Adding the block to your theme
In your Shopify admin, go to **Online Store > Themes**, then click **Customize** on your active theme.
In the Theme Editor, use the page selector at the top to switch to a **Product page** template.
In the left sidebar, find the product page section and click **Add block**. Look for **Unified purchase selector** under the **Apps** section and select it.
Drag the block to position it where you'd like it to appear — typically near the "Add to cart" button so customers can select their purchase option before adding to cart.
Click **Save** in the top right corner to publish your changes.
### Configuration options
Customize the block's appearance directly in the Theme Editor sidebar:
| Setting | Description | Default |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| **Theme mode** | Light or dark appearance | Light |
| **Primary color** | Color for active states and highlights | `#397971` |
| **Corner style** | Border radius — sharp, subtle, rounded, or very rounded | Rounded (8px) |
| **Spacing between options** | Gap between subscription options — tight, default, or relaxed | Default |
| **Padding inside cards** | Internal card padding — compact, default, or spacious | Default |
| **Text size** | Scale all text — small, default, or large | Default |
| **Collapse unselected purchase options** | Fold unselected options down to their header row — only the selected option shows its full details. The fold is animated and respects reduced-motion preferences. Turn off to keep every option expanded | On |
| **Header font weight** | Normal, medium, or bold | Normal |
| **Price font weight** | Normal, medium, semi-bold, or bold | Semi-bold |
| **Show discount badge** | Display a badge when a subscription offers a discount | On |
| **Badge color** | Background color for the discount badge | `#397971` |
| **Badge style** | Pill (rounded), square, or tag (angled) | Pill |
| **Frequency label** | Text shown above frequency options. Only displayed for consumable subscriptions — hidden for non-consumable products (e.g., rentals) | "Deliver every:" |
| **Show subscription benefits** | Display subscription benefit text below options | On |
| **Benefit icon style** | Checkmark, bullet, or none | Bullet |
| **Benefit text: Discount** | Customizable benefit message. Leave empty to hide | "Save on every order" |
| **Benefit text: Flexibility** | Customizable benefit message. Leave empty to hide | "Change, pause or cancel anytime" |
| **Pre-selected purchase option** | Which option starts selected on page load — automatic (buy → subscription → rental), one-time purchase, subscription, or rental. Options the product doesn't offer fall back to the automatic order | Automatic |
| **Show one-time purchase option** | Whether to show the one-time purchase option alongside subscriptions. Uncheck to show subscriptions only | On |
| **One-time purchase label** | Text for the one-time purchase option | "One-time purchase" |
#### Subscription bundle card
These settings only apply when a product belongs to a [bundle](/docs/mintlify/create-bundles). They control the dedicated bundle card the block renders in place of the normal subscription options.
| Setting | Description | Default |
| ----------------------------- | -------------------------------------------------------------------------------- | --------------------- |
| **Bundle card heading** | Title shown above the bundle CTA. | "Subscription bundle" |
| **Bundle CTA label** | Text on the "Add to bundle" button. | "Add to bundle" |
| **Manage subscription label** | Button label shown when the customer already has an active bundle for this plan. | "Manage your bundle" |
| **Bundle primary color** | Header band, progress bar fill, and primary CTA color. | `#e8418e` |
| **Bundle accent color** | Card body background. | `#fdc404` |
### The theme's own buy buttons
Your theme renders its own **Add to cart** and **Buy it now** buttons on the product page. With the Unified purchase selector installed they're redundant — and they skip the selector's checks (rental date booking, subscription start date), so a customer could add a rental to the cart without picking any dates.
The **Hide the theme's buy buttons** setting hides them for you — it's off by default so your current layout doesn't change, and we recommend turning it on.
Hide the buttons with the setting (or inside the theme's **Buy buttons** block settings) — but don't **remove** the Buy buttons block from your theme. On most themes it provides the product form the selector relies on; removing it can break add-to-cart entirely.
## Cross-sell Products block
The **Cross-sell Products** block renders the slim cross-sell list on the product page. Adding it to your theme is the same flow as the Unified purchase selector — pick **Cross-sell Products** from the **Apps** section in the Theme Editor.
Configuration of *which* products appear, *which* are forced one-time, and how mirroring behaves all lives in the app under **Cross-sell**, not in the theme.
Configuring cross-sells, frequency mirroring, force-one-time mode, block settings, and eligibility rules.
## Bundle progress block
The **Bundle progress** block lives on the cart page or cart drawer. While the customer is filling a [bundle](/docs/mintlify/create-bundles), it shows the bundle name, a `N / capacity` counter, a progress bar, and a **Reset bundle** button. Once the bundle is full, the block surfaces a **Manage bundle** link to the bundle manage page.
If the cart contains no active bundle, the block hides itself — there's no setup cost to leaving it placed.
### Adding the block to your theme
In your Shopify admin, go to **Online Store > Themes**, then click **Customize** on your active theme.
In the page selector at the top of the Theme Editor, switch to the **Cart** template (or open the cart drawer preview, depending on your theme).
Click **Add block** in the cart section and pick **Bundle progress** under the **Apps** group.
Place it above the cart line items so the counter is the first thing the customer sees while assembling the bundle.
Click **Save** in the top right.
The Bundle progress block has no configuration options — it inherits its appearance from your theme. To customise the matching PDP card, use the **Subscription bundle card** settings on the Unified purchase selector block above.