Skip to main content
  1. Recharge
  2. Products & subscriptions
  3. Subscription widget
  4. Using the subscription widget
Note: Recharge is rolling out a new merchant portal experience. You may notice that some articles still reflect the old navigation. We are in the process of updating our guides to reflect these changes.

How to set up and customize the Subscription Widget

Relevant to: Shopify Checkout Integration Migrated Shopify Checkout Integration

The Subscription Widget empowers you to take your subscription offerings on the Shopify product page to the next level through a highly customized customer experience.

This guide provides set-up instructions so you can use the widget on your storefront. 

Platform:

  • Shopify Checkout Integration
  • Migrated Shopify Checkout Integration

Before you start

Approve the widget scopes

The first time you use the Subscription Widget, you’ll need to approve the required widget scopes in Shopify:

  1. Select Cross-Sell & Upsell in the merchant portal and click Product page.
  2. Click Get started.
  3. Click Approve permissions in Shopify to open your Shopify admin.
  4. Click Update. This will enable the following scopes:
    1. write_pixels
    2. read_customer_events
    3. read_markets
  5. Navigate back to the Product page in Recharge and click Get started again to design the widget.

Step 1 - Create the widget

Recharge offers a setup wizard to help you create your widget or flow canvas for A/B testing. See How to A/B test a Subscription Widget to learn more about setting up an A/B testing experience.

Use the set-up wizard to create your Subscription Widget:

  1. Select Cross-Sell & Upsell in the merchant portal and click Subscription widget.
  2. Click Create widget from template.
  3. Select Standard widget.
  4. Click Get started.
  5. Select a starting point for your widget. Use the Default configuration as your starting point, or, if you’ve created a widget before, select one of your existing widgets as a template. Then, click Set starting point to continue.

Step 2 - Review your audience

By default, when activated, Recharge displays the subscription widget to all customers whenever they open a product page for a subscription product.

You can keep this as is, or add a condition so the subscription widget appears only when a product uses a specific product template.

Select Mark as done & continue on the Review your audience setup step to move on to the next step, or follow the instructions below to ensure the widget only appears on specific product pages:

  1. Click on the pencil icon to open the editor.
  2. Click Add to add a condition.
  3. Select Add product template to choose the template.
  4. Choose a product template from the available templates. You can choose multiple templates.
  5. Click Apply to set the condition.

Step 3 - Customize the widget experience

Create and customize your widget directly in Recharge:

  1. Click Review & customize under the Review & customize experience step.
  2. Update the following settings to edit and customize the widget experience:
  3. Click Done after customizing the widget.
  4. Select Mark as done, then continue to the next step.

Use the widget preview on the right side of the page to see your changes in real time. The widget preview may not display all customizations, as some settings are specific to certain subscription plan types. Be sure to adjust your plan type to view the applicable customizations. For example, the dynamic pricing setting only appears when you select the dynamic pricing plan type.

Default selections

Use the Default selections tab to confirm if customers should:

  • Have the subscription or the one-time version of the product immediately selected when they access the product page
  • See the one-time or subscription version of the product first when they access the product page
Tip: Recharge recommends allowing customers to purchase the product as a subscription by default, as data show that customer LTV is significantly higher among subscribers.

Styling

Change the widget colors, border radius, and size on the Styling tab.

Labels and inputs

Update the widget labels, such as “Subscribe and save”, “One-time” or the delivery frequency options.

Badge

Update the text and color for the subscription discount badge on the widget.

Recharge only displays the badge for products that include a Subscribe and Save discount and are offered as one-time purchases.

Benefits and information

Use this section to update the messaging customers see on the product page. This content encourages customers to choose a subscription by clearly highlighting:

  • The subscription discount
  • The benefits of subscribing
  • What customers miss out on with a one-time purchase
Tip: List benefits and drawbacks in bullet points. If you don’t use bullet points, they won’t display correctly on the product page.

Section

Explanation
Show strikethrough price

Enable Show strikethrough price to display the one-time price crossed out next to the discounted subscription price.

This helps customers immediately see the value of subscribing.
Static pricing Use this field for products with standard subscription or prepaid plans.
Dynamic pricing Use this field if your product has dynamic pricing (for example, a larger discount on the first order and a smaller discount on recurring orders).
Benefits

Use this section to highlight the advantages of subscribing. Enter each benefit as a bullet point. You can use the variable: {discount}to highlight savings.

Example:

  • Save {discount}
  • Flexible delivery frequency
  • Skip, reschedule, or cancel anytime

Toggle the Display benefits only on the selected purchase option setting to control whether benefits show for the selected purchase option only (enabled by default) or always remain visible regardless of selection. 

Keep your benefits short and easy to scan.
Benefits image

Upload an optional image to visually support your subscription messaging, with a recommended width: 398px.

Use a simple, on-brand image that reinforces the value of subscribing.
One-time drawbacks

Use this section to highlight what customers miss out on if they choose a one-time purchase. Enter each drawback as a bullet point.

You can use the variable: {maxDiscount}

Example:

  • Miss out on {maxDiscount} in savings
  • No subscriber-only perks
  • No flexible delivery options

This helps clearly contrast the value of subscribing versus purchasing once.
Learn more link text

Enter the text customers click to open the subscription details modal.

For example:

  • Learn more
  • How subscriptions work

Leave this field blank if you don’t want to display the link.
Learn more modal content

Recharge provides a default HTML and CSS template that highlights common subscription benefits. You can keep the default content or customize it using your own HTML and CSS.

When editing this content:

  • Clearly explain how the subscription works
  • Include pricing and renewal details
  • Explain how customers can manage or cancel

It's important to check local and national laws to ensure you provide all required subscription disclosures, including pricing, renewal terms, and cancellation policies.
Interval labels

Update the interval labels used to display subscription frequencies, such as “day,” “week,” or “month.”

For translation instructions, see How can I translate the Subscription Widget?

Interval labels

Update the interval labels used to display the subscription frequencies for the product, such as “day”, “week”, or “month”.

Tip: See How can I translate the Subscription Widget? for detailed translation instructions.
Variables

Use the following variables when designing your widget content:

Section

Variable

Description

Example
Labels and inputs > Frequency save {discount} Inserts the discount value (percentage or amount) applied when a customer chooses a subscription frequency. Save 15% when you subscribe monthly.
Badge > Badge Text {maxDiscount} Displays the maximum available discount across all subscription frequencies. Up to 25% off with subscription
Badge > Badge Text {discount} Inserts the discount value (percentage or amount) applied when a customer chooses a subscription frequency. Save 15% when you subscribe monthly.
Benefits and information > Static pricing {discountPrice} Displays the discounted product price after applying the subscription discount. Only $18.99 per order.
Benefits and information > Dynamic pricing {initialDiscountAmount} Displays the discount amount applied to the first order only. Get $5.00 off your first box.
Benefits and information > Dynamic pricing {initialDiscountPercentage} Displays the discount percentage applied to the first order only. Enjoy 20% off your first order
Benefits and information > Dynamic pricing {recurringDiscountAmount} Displays the discount amount applied to each recurring order. Save $3.00 on every renewal.
Benefits and information > Dynamic pricing {recurringDiscountPercentage} Displays the discount percentage applied to each recurring order. Enjoy 10% off every delivery.
Benefits and information > Dynamic pricing {recurringDiscountCount} Displays the number of recurring orders the discount will apply to. Discount applies for the first 3 orders
Benefits and information > Dynamic pricing {recurringDiscountCountWithInterval} Displays how many orders and at what interval the discount applies. Discount valid for 3 monthly orders.
Benefits and information > Benefits {discount} Inserts the discount value (percentage or amount) applied when a customer chooses a subscription frequency. Save 15% when you subscribe monthly.
Benefits and information > One-time drawbacks {maxDiscount} Displays the maximum discount customers miss out on if they buy as a one-time purchase instead of subscribing. You’ll miss out on 25% savings by ordering one-time.
Interval labels {interval} Inserts the interval number (e.g., 1, 2, 3). Deliver every 2 weeks.
Interval labels {chargeInterval} Combines the interval number with the unit (day, week, month). Charge every 3 months.
Interval labels {unitPrice} Displays the price per unit when sold as part of a subscription. Only $2.50 per bottle

Step 4 - Add the widget app block to your Shopify theme

Add the widget app block to the product page in your Shopify theme:

  1. Select Configure app block in Shopify under the Make visible on your storefront step to open the Shopify Theme Editor.
  2. Use the Page Selector drop-down at the top of the page to switch from the Home Page to the Product page. Select the relevant Product Template or use the default one.
  3. Review the Product page. Make sure to view the product page for a subscription product.
  4. Click Add section and select Apps.
  5. Select Subscription Widget depending on your plan and the type of widget you are creating.
    Drag and position the widget as needed.
  6. Save your changes.
  7. Optional - Repeat Steps 4-9 to add the widget to additional product templates.
  8. Open the Recharge Subscription Widget setup tab, then select Mark as done & continue.

Step 5 - Finish setup

Name your widget and activate it when ready:

  1. Open the Finish setup step and add a name and description to your widget.
  2. Click Mark as done.
  3. Select Activate flow to publish your widget, or Save the widget and activate later.

Step 6 - Test the widget on your storefront

Confirm that the widget acts and appears as you intended:

  1. Navigate to your Shopify storefront.
  2. Open the product page for a subscription product.
  3. Confirm that the widget appearance matches what you set in your Recharge merchant portal.

You can finish testing your widget here, or perform a test order to test the customer experience completely.

Edit the widget

You can change the standard widget experience at any time, even after you activate the widget. This includes updating your audience, adding conditions, changing the default selection from one-time or subscription, and editing labels and styles.

  1. In the merchant portal, click Cross-sell & Upsell.
  2. Under Storefront, select Subscription widget.
  3. Click the name of the Subscription Widget you want to edit. 

A/B discount testing Early Adopter Program

Recharge now supports A/B testing for Subscribe and Save Discounts through the Early Adopter Program. This allows you to test multiple discount values for the same subscription frequency. For example, you can offer a 1-month subscription with both a 10% and a 15% discount to determine which performs better. Complete the A/B Discount Testing Early Adopter Program form if you're interested in participating.

Set up instructions:

Use A/B tests and insights to improve your product page performance.

  1. Create a new widget and select the A/B testing discount template.
  2. For an existing widget, you can set it as your default design before configuring the A/B test. This way, you avoid designing the widget from scratch.
  3. Ensure the Trigger node targets the product (not the product template).
  4. The Subscription widget node now displays available plan discounts:
    • Path A displays the existing plan setup in the Plans section.
    • Path B is where you create the different discount values.
  5. You can customize the subscription widget’s look and feel the same way via the View Subscription widget.

Available features to assess:

You now have additional features to improve your product page performance:

  • Discount percentage value: Set your subscription discount amount
  • The order of the plans: Change the default highlighted plan and adjust the sort order
  • The visibility of the plan: Show or hide specific plans on the widget
Warning: If you re-order your selling plans on the B path and determine it is the winning path, you need to deactivate the widget, then re-order the plans to reflect that order on your new A path or new static widget if you want it to be the winner.

Review Analytics

View widget analytics to track its performance. Tracking starts automatically as soon as you activate your widget, allowing you to monitor add-to-cart clicks and their resulting checkouts. Widget analytics excludes data from accelerated checkout buttons.

Click on the Performance tab to access the widget analytics.

  1. Review the widget analytics to gather more information on the following data points:
    • Subscriber opt-in rate
    • Page impressions
    • Revenue
    • Add-to-carts
    • Checkout revenue
  2. Use the Product, Template, Flow, or A/B test filters to filter your data and understand how customers interact with the widget.
Note: Recharge does not calculate the Subscriber Opt-in Rate for Subscription Orders if your theme uses the checkout.liquid theme file to customize the checkout experience. You must upgrade your Shopify Thank you page to ensure accurate tracking. Without Checkout Extensibility enabled, all subscription orders appear as one-time purchases (OTPs) in your Subscription Widget Analytics.

Discrepancies between data sources

Subscription Widget analytics uses front-end pixels, which may result in missing data. It is expected that the data shown on the Subscription Widget Performance tab may differ from data available in Shopify, or other Recharge Analytics data.

Recharge doesn’t recommend relying on Widget Analytics as exact figures or a source of truth. However, this data is valuable for understanding trends and measuring the performance of your widget to optimize conversion rates and improve the customer experience.

Considerations

Consider the following when using the Subscription Widget or Advanced Subscription Widget:

Consideration

Notes
Bundles
  • Fixed-price and Dynamic bundles use their own widgets to display the bundles option to customers.
  • Preset bundles use the Subscription Widget. You can create a bundles-specific product page template, and then design a widget to display on this template that specifically highlights the benefits of your bundled products.
Product Subscription Plans
  • You must have Product Subscription Plans enabled to use the Subscription Widget. Follow the instructions listed on How to convert to Product Subscription Plans if you wish to upgrade to use the widget.
  • The widget respects the sort order of your product subscription plans set for a product.
  • The plans list on the widget resets if you change the order of the product's plans. You cannot select specific frequencies to display first, instead at this time frequencies are preselected.
Page builder apps
  • Page builder apps such as Pagefly and Shogun are not compatible with the Subscription Widget out-of-the-box.
Shopify themes
Shopify Markets

An example of the widget translated into Spanish
Price label
  • The price label on the product page does not update when switching between one-time and subscription options due to a Shopify limitation.
  • The price does display on the widget to help prevent customer confusion. 
Quantity adjustments pricing
  • The subscription widget does not dynamically update the displayed price when a customer adjusts the quantity on the product page. The displayed price remains fixed based on the initial quantity selection.
Payment
  • If you use manual payment capture or authorization capture on Shopify, the order isn't paid at checkout. In these cases, widget analytics only reflect the checkout information after you successfully capture the payment.
Compare at price
  • The widget does not display the Shopify compare-at-price.
Advanced customizations
  • Customizations to the product page can interfere with the subscription widget and cause the error "Variant can only be purchased with a selling plan."
  • This happens when the selling plan isn’t correctly passed to the cart, preventing successful subscription purchases. If you’re adding custom elements to the product page, work with a developer to ensure your changes properly integrate with the subscription widget.
Widget placement
  • The Subscription Widget only works on product page templates. You cannot place the widget on other pages, such as your storefront's home page.

Resources

Getting Started resources

Set-up instructions

Troubleshooting resources

Frequently Asked Questions

Developer Docs

Was this article helpful?
0 out of 0 found this helpful

Related articles

Didn’t find what you’re looking for?

Contact us