Thanks for installing the new PayWhirl + Shopify App. This installation guide is intended to take you through the setup process to begin selling subscriptions and other types of payment plans on Shopify. Please let us know if you have any questions!

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

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

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 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
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" and then 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.

Plan selector title - This is displayed when customers view your selling plan group options on the product page.

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). In our example, we'll select 1 for the interval and weekly for the frequency settings, so the customers are charged weekly.

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, then orders will be generated every week.

Note: Pre-Paid plans that ship multiple times in between billing are coming soon.

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:

In our example, we've opted to give 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.

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.

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.

If you use an older Shopify theme or your theme doesn't support app blocks, we'll display specific instructions on how to edit the product page code in your theme to use PayWhirl.

Please let us know if you have problems installing, and we'll do our best to provide specific instructions for your theme ASAP. We can also recommend Shopify experts and theme developers who can help customize unsupported themes while we work to expand support for more themes.

Let's continue with an example for themes that do not support app blocks. We'll install the PayWhirl snippets manually. Installation instructions can be found in the app's main menu under the "Theme Snippets" menu item.

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.

To add the customer portal, you simply use the "customize" option on your theme and turn on the PayWhirl App Embed.

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

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 assistance, please reach out to 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!

If the Paywhirl App Embed is not able to automatically add code snippets to your theme, please see the instructions for adding them manually:

1. Customer Portal link

The goal is to add a link somewhere on your main "account" page so customers can navigate to their subscription details. You have to add the code listed below, into 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.

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.

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.

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.

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) works.

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.

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

The PayWhirl Team