Overview
The circuly Subscriptions theme extension adds two blocks to your Shopify storefront:- Payment Options — A subscription widget on product pages that lets customers choose between subscription plans and one-time purchase
- Cross-Sell Grid — A product recommendations section that displays related products configured via metafields
Payment Options block
The Payment Options 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
Open the Theme Editor
In your Shopify admin, go to Online Store > Themes, then click Customize on your active theme.
Navigate to a product page
In the Theme Editor, use the page selector at the top to switch to a Product page template.
Add the block
In the left sidebar, find the product page section and click Add block. Look for Payment options under the Apps section and select it.
Position the block
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.
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 | Gap between subscription options — tight, default, or relaxed | Default |
| Padding | Internal card padding — compact, default, or spacious | Default |
| Text size | Scale all text — small, default, or large | Default |
| 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 | ”Deliver every:“ |
| Show benefits | Display subscription benefit text below options | On |
| Benefit icon style | Checkmark, bullet, or none | Bullet |
| Benefit text: Discount | Customizable benefit message | ”Save on every order” |
| Benefit text: Flexibility | Customizable benefit message | ”Change, pause or cancel anytime” |
| Default purchase option | Pre-selected option on page load — one-time or first subscription | One-time purchase |
| Show one-time purchase | Whether to show the one-time purchase option alongside subscriptions | On |
| One-time purchase label | Text for the one-time purchase option | ”One-time purchase” |
Cross-Sell Grid block
The Cross-Sell Grid displays recommended products on the product detail page. Products are configured via acustom.cross_sell_products metafield on each product.
Adding the block to your theme
Follow the same steps as the Payment Options block, but select Cross-sell Products from the Apps section when adding a block.Setting up cross-sell products
To configure which products appear in the cross-sell grid for a specific product:Go to Products
In your Shopify admin, go to Products and open the product you want to add cross-sell recommendations to.
Add the metafield
Scroll down to the Metafields section and find the Cross-sell products field (namespace:
custom.cross_sell_products, type: Product list).Select products
Click the field and choose the products you want to recommend alongside this product.
If the metafield doesn’t appear in your product editor, you may need to add a metafield definition first. Go to Settings > Custom data > Products and create a metafield with the namespace
custom.cross_sell_products and type Product list.Configuration options
| Setting | Description | Default |
|---|---|---|
| Display style | Grid or carousel layout | Grid |
| Products per row | Number of products per row (2–4) | 3 |
| Gap between products | Spacing between product cards (8–32px) | 16px |
| Show heading | Display a heading above the grid | On |
| Heading text | The heading text | ”Complete your order” |
| Show prices | Display product prices on cards | On |
| Show vendor | Display the product vendor | Off |
| Show subscription toggle | Let customers choose between subscription and one-time purchase | On |
| Enable click-to-add mode | Clicking a card adds it to cart immediately | On |
| Theme mode | Light or dark appearance | Light |
| Primary color | Accent color for buttons and highlights | #397971 |
| Corner style | Card border radius | Rounded (8px) |
| Top/bottom margin | Spacing above and below the grid (0–100px) | 32px |
Debug mode
If the cross-sell grid isn’t showing, enable Debug mode in the block settings. This displays diagnostic information including:- Whether the metafield exists on the product
- How many products are in the metafield
- Which products are available vs. unavailable
- Why the grid isn’t rendering