Skip to main content
All CollectionsShopify Subscription AppSetup and Getting Started
Getting started with the PayWhirl subscription app for Shopify
Getting started with the PayWhirl subscription app for Shopify

Quickstart guide and setup instructions for PayWhirl's Shopify app.

Ryan P. avatar
Written by Ryan P.
Updated over a week ago

Welcome to PayWhirl Subscriptions for Shopify. This installation guide will take you through the setup process to begin selling subscriptions and other recurring payment plans on Shopify. Please let us know if you have any questions!

Getting started with PayWhirl's new Shopify app...

1) Add PayWhirl to your store from the Shopify App Store

2) Create selling plan groups

When you first log in, you'll see the dashboard with setup instructions to configure the app. To begin, you'll need to create selling plan groups in the app.

There are two options to configure your selling plans:

Simple Plan Editor - The simple editor is perfect for creating a simple subscription option that can be attached to products to offer recurring purchase options to customers. By default, it's prefilled to create a basic monthly subscription that will bill and place orders after payments are collected each month.


The simplified selling plan editor is located on the Getting Started page, where you click the Create Selling Plan button.

You can change the values as needed before saving your plan. You can use our full editor for more advanced configuration options (more info below).

Full Plan Editor - This is the complete plan builder and includes all of the available subscription options. Learn more...

The full selling plan editor is located on the Plans page, where you click the Create button at the top-right corner.

Selling plan groups are additional payment option(s) that will be added to your products in Shopify. You can set up multiple selling plans within a selling plan group.

In this example, we will set up a selling plan group called "Subscribe and Save" using the full plan builder, and then we'll add the group to several products in our store. The selling plan group will have two selling plans (weekly and monthly) subscription options for customers.

First, we will set up the selling plan group details for "subscribe and save." This will be an 'ongoing subscription' which uses the basic setup process

Subscription plan name - This is the name of the selling plan group, and it's shown to customers on the product page to distinguish a one-time purchase from a subscription.


Plan selection display label —This is displayed when customers select a subscription plan group on the product page. It typically includes the frequency and discount.

This defaults to 'deliver every,' but you can customize it by clicking on the advanced settings:

Note: Depending on your theme, it might look slightly different than the screenshots above. Each theme can style and place elements in different locations, but generally, this is how these settings will be displayed to customers.

Next, we will set up our weekly and monthly selling plan options so customers can select a frequency that works for them. We'll start with a weekly selling plan.

Subscription plan name - This is the name of the selling plan that will be displayed to customers in your cart, during checkout, and potentially on product pages (depending on your theme).

It is usually a good practice to include the frequency in the name. This way, customers can see what they selected in various parts of your theme, like the cart and checkout.

Theme Cart Preview

Subscription selection display label - This is the name of the selling plan that will be displayed to your customers on the product page where they select their subscription options.

Next, we'll set up the billing rules for the selling plan in the bottom section of the selling plan settings. These settings will control how the selling plan bills your customers repeatedly.

Delivery Frequency - This setting has two controls. It allows you to choose how often the selling plan will bill your customers and on what frequency (daily, weekly, monthly, yearly).

If you wanted to bill the customers every two weeks, you'd select 2 for the interval and the weekly frequency.

The interval settings also control how often orders will be generated in your Shopify store. For example, if your selling plan bills the customer every week, orders will be generated weekly.

In our example, we'll select 1 for the interval and weekly for the frequency settings, so the customers are charged weekly.

Description - This is displayed to customers on product pages after they select a specific selling plan. It's a good place to provide extra information about the specific selling plan and appears as a text block.



Discount or manual price - This setting controls the pricing for the selling plan and works with the "adjustment value" setting.

There are four options for pricing selling plans:

  • None (not recommended)—Keeps the price the same as the selected product variant, with no adjustment. Adding a discount for recurring payments can increase subscription conversion rates.

  • Fixed Amount Discount (recommended): This option lets you select a specific amount to discount the product variant if customers buy the selling plan.

  • Percentage Discount (recommended): This option lets you select a percentage-based amount to discount the product variant if customers buy the selling plan.

  • Manual Price - Let you specify a manual price for the selling plan.

In our example, we've offered customers a 15% discount for subscribing to weekly deliveries. This is commonly referred to as "subscribe and save" and is usually well-received by customers.

Next, we'll add our monthly subscription option to the selling plan group by selecting the "Add selling plan" link at the bottom of the page. In our example, we'll give customers a 10% discount for monthly subscriptions.

Toggle to the Prepaid or custom/advanced plan type to access additional settings

Additional Options include Prepaid deliveries, Anchors, Cutoff windows, Max/Min Payments, and Finishing behavior.

Prepaid Deliveries- The number of deliveries billed upfront by this plan, IE 2 deliveries billed upfront that are to be delivered every 1 week.

Anchor day- Day of the week or month to schedule orders and billing.

First Delivery - Sets the timing for the initial checkout when an anchor date is specified. On checkout will make the order available for fulfillment immediately after purchase. The on anchor setting will schedule the first delivery to be ready for fulfillment on the next anchor date.

Order cutoff window—This setting can be combined with anchor dates and first delivery settings to determine how orders work as the checkout date approaches the anchor date. IE How to handle checkouts that happen right before the anchor date.

Minimum number of installments before the customer can cancel -This setting controls the minimum number of payments the customer must make before canceling the subscription from the customer portal. This is disabled by default and will require the merchant to cancel subscriptions manually via the admin if customers need to make changes before the minimum term has been met.

Max number of fulfillments—This setting lets you control whether subscriptions should be ongoing (indefinitely) or canceled automatically after a specific number of payments have been completed. By default, it's set to unlimited, making the subscription continue to rebill until the customer or the merchant cancels it.

3) Associate selling plan group(s) with Shopify products

Now that we've created a selling plan group with two options, we're ready to add the selling plan group to specific products in our store.

There are two ways to associate selling plans to products with PayWhirl

  • Directly from your Shopify product page under the 'selling options' section.

  • In bulk from the PayWhirl app on the selling plan settings page.

Adding Subscription Options from Shopify Product Settings

Edit the Shopify product(s) you'd like to sell on a subscription basis and select the "Add option" link on the subscription card to add your existing selling plan group(s) from the PayWhirl app.


Note: You can also create a selling plan group directly from your product page by selecting "Add new option" from the dropdown menu on the subscription card. This option uses our "simple plan editor" and doesn't contain all the features of the main editor in the app.

After you've associated your Shopify product(s) with selling plan groups from PayWhirl, you'll see the subscription details displayed in your product page settings.

Note: Associating selling plan groups from the main product page in Shopify will apply the subscription options to ALL the variants of your product. If you only want the subscription options to apply to specific variants, you can add them from the variant details page in Shopify.

Add subscription options from the PayWhirl app in bulk

If you'd like to add your subscription options to multiple products or entire collections at once, you can do so from the selling plan settings in the PayWhirl app by clicking the Add products button in the top right corner of the selling plan group details page.

PayWhirl App > Plans > Edit Selling Plan Group > Add Products

On the Add / Edit Products page in PayWhirl, you can associate your subscription selling plans with products or remove/adjust them in bulk.

You can click the Add button next to each product, which will only add the selling plan to that specific product, or you can select multiple using the checkboxes and select Add in bulk to apply them to multiple at once.

4) Integrate with your theme

At this point, we've created selling plan groups and associated them with our products on Shopify. However, customers will not see anything until we integrate our theme with PayWhirl.

PayWhirl integrates with most themes in the Shopify theme store and elsewhere. If you need help with installation, please get in touch with our team via chat so we can request access to assist.

There are two different installation options, depending on your Shopify theme. We'll detect the version of your theme automatically and provide you with the correct installation options based on your Shopify theme version. If you use a Shopify 2.0 or newer theme, you can utilize the PayWhirl App Block (released in June 2022), so you don't have to edit any code in your theme.

PayWhirl installation for Shopify 2.0 themes

  1. Navigate to your published theme in Shopify.

  2. Click Customize to view your theme settings.

  3. Navigate to a product page in your theme settings.

  4. Add the PayWhirl app block to your product page.

  5. Save your changes.

Installing the customer portal in your theme (1 min into the video above)

Installing our PayWhirl app embed to your Shopify theme is the most seamless way to integrate PayWhirl's customer portal. The result will be a single login for customers to access your store and their subscriptions. To add the customer portal app embed, use your theme's "customize" option and turn on the PayWhirl App Embed.

The PayWhirl App Embed allows you to automatically add the following snippets to your theme simply by checking them in the App Embed settings:

  • Customer Portal link

  • Customer login page note

  • Account addresses edit form note


If any of the above doesn't show up in your theme, you can use the following instructions to add these snippets manually. If you need help, please don't hesitate to contact our support team, and we'll help with the installation.

After you've installed the customer portal and added a link to view it, you can log in to your website to ensure it works well and that the link is in an optimal location for customers. If you have any questions or need assistance, please let us know!

PayWhirl installation for themes that don't support app blocks

You can manually install the required theme code using an older Shopify theme that doesn't support app blocks. Please don't hesitate to let us know if you have questions or problems. We'll do our best to help with installation or provide specific instructions for your theme as soon as possible.

We can also recommend Shopify experts and theme developers who can help customize unsupported themes if necessary.

Let's continue with an example of themes not supporting app blocks. We'll install the PayWhirl snippets manually. Installation instructions are in the app's main menu under "Getting Started."

Manual Installation Preview

After you've installed the required snippets, you should be very close to a finished integration. However, in some cases, you may need to add a few lines of code to your theme to finish the installation.

Manual customer portal snippets installation

If the Paywhirl App Embed cannot automatically add code snippets to your theme for the customer portal, you have two options.

  1. Installing the snippets manually (recommended; more on this below)

  2. Using Shopify's new customer accounts feature with PayWhirl's hosted portal version. Please get in touch with our team if you are interested in learning more.

1. Manual Customer Portal Link Installation

The goal is to add a link on your main "account" page so customers can navigate their subscription details. You have to add the code listed below to the account template. Usually, the template file is located under templates/customers/account.liquid. The link can be placed anywhere, but we recommend a prominent location so it's easy to find.

<p><a href="{{ routes.account_url | append: "?pw-page=/" }}">Subscriptions</a></p>

2. Customer login page note
Add the following message before all occurrences of {{ form.set_as_default_checkbox }} in templates/customers/addresses.liquid template file.

<p><center>
Changing your default address does not affect existing subscriptions.
If you'd like to change your delivery address for recurring orders, please visit the
<a href="{{ routes.account_url | append: "?pw-page=/" }}">subscription page</a>.
</center></p>

3. Account addresses edit form note

Add the following message at the end of the customer_login form in templates/customers/login.liquid template file.

<p>In order to access your subscriptions, create an account with the same email address</p>

Note: The Shopify theme editor has built-in version control, so you can revert to a past code version if anything isn't working properly. If you'd rather not edit your code, please reach out to our team, and we'll do our best to help or refer you to a Shopify expert who can assist.

5) Review settings, test transactions, and launch!

After you've installed the snippets and finished copying/pasting your includes in your theme, you should be able to see your subscription options on the product pages you associated with selling plan groups.

Lastly, you should look over the app settings to make sure you've enabled the options you want for customers who access their customer portal. You can also specify how failed payments (dunning) should work.

That's a wrap! Once you've completed the steps above, you can test a live transaction or enable test mode in Shopify Payments and run some test transactions to see how subscription orders are generated.

CLICK HERE TO SEE THE MANUAL THEME INSTALLATION FOR SHOPIFY THEMES THAT DON'T SUPPORT APP BLOCKS... or contact our support team, and we'll help with setup or any other issues you have.

Please let us know if you have any questions. We're happy to help!

The PayWhirl Team

Did this answer your question?