Welcome to PayWhirl Subscriptions for Shopify. This installation guide is intended to 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...

Install the PayWhirl app
Create selling plan groups
Associate selling plan group(s) with Shopify products
Integrate with your existing theme
Review settings, test transactions, and launch!

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

2) Create selling plan groups

You'll see the dashboard with setup instructions to configure the app when you first log in. 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.

You can locate the simplified selling plan editor from the getting started page by clicking the Create Selling Plan button.

You can change the values as needed before saving your plan. You can use our full editor if you need 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...

You can locate the full selling plan editor from the Plans page by clicking the Create button in 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."

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 selector title - This is displayed when customers select a subscription plan group on the product page. This typically will include 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.

Full 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 from just about any screen.

Theme Cart Preview

Plan Selector 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.

Interval - 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.

Selling Plan Description (advanced settings) - 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.

Min number of installments before the customer can cancel -This setting will control how many payments the customer must make before canceling the subscription from the customer portal.

This is helpful if your subscriptions require customers to be subscribed for a minimum number of payments. 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 if subscriptions should be ongoing (continue indefinitely) or be canceled automatically after a specific number of payments have been completed.

By default, it's set to unlimited which will make the subscription continue to rebill until the customer or the merchant cancels it.

For example, if you wanted a subscription to last for three payments, you would set the max number of fulfillments to 3, and the system would automatically cancel the subscription after three payments were completed.

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 conversion rates for subscriptions.
Fixed Amount Discount (recommended) - This lets you select a specific amount to discount the product variant if customers buy the selling plan.
Percentage Discount (recommended) - This 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 subscribing monthly.

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.

You can associate selling plan groups to products in Shopify directly from your product page settings. Alternatively, you can add subscriptions to products or entire collections 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 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 have associated them with our products on Shopify. However, nothing will be visible to customers until we integrate our theme with PayWhirl.

PayWhirl integrates with most of the themes in the Shopify theme store and elsewhere. If you need help with installation, please reach out to 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

Navigate to your published theme in Shopify.
Click Customize to view your theme settings.
Navigate to a product page in your theme settings.
Add the PayWhirl app block to your product page.
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 manually add these snippets. 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

If you use an older Shopify theme that doesn't support app blocks, you can manually install the required theme code. 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 is not able to automatically add code snippets to your theme for the customer portal, you have two options.

Installing the snippets manually (recommended, more on this below)
Using Shopify's new customer accounts feature with PayWhirl's hosted version of the portal. This feature is in beta, so 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 review the app settings to ensure 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.

MANUAL THEME INSTALLATION FOR SHOPIFY THEMES THAT DON'T SUPPORT APP BLOCKS

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

The PayWhirl Team