Skip to main content
Installation guide
Michiel Sikkes avatar
Written by Michiel Sikkes
Updated this week

This guide explains all the steps that you as a merchant (in combination with your agency/developer) need to do, to get started with selling subscriptions via Shopify Native Checkout powered by Firmhouse.

πŸ‘‰ Our native Shopify Checkout integration is currently in public beta but we're happy to help you get set up and take all your feedback so we can iterate, improve, and prioritize the most important next steps in our integration.

Please review Supported Checkout and Subscription capabilities for an up-to-date list on current and upcoming features and improvements.

Prerequisites / Good to Know

There are a few items that are good to be aware of when joining the beta. Some of these things may change as we come out of beta:

  • All purchases will go through Shopify Cart and Shopify Checkout.

  • Using the Firmhouse SDK or APIs to build a cart and Checkout is not supported in combination with Shopify Native Checkout. You have to use native Shopify APIs to build your store.

    • However, after a Subscription is started and activated in Firmhouse based on a Shopify Checkout, you can use Firmhouse SDKs and APIs to manage Subscriptions via the Firmhouse API.

  • You will have to enable Shopify Payments to offer Credit Cards and PayPal for subscriptions.

  • You'll need a payment provider account at Mollie with SEPA enabled to support iDeal, Bancontact, and future local payment methods we support. This may change as Shopify may add support for local payment methods in the future.

  • Firmhouse offers a "Subscription Options" widget that can be embedded on your product detail pages via the Shopify theme editor. However, if you currently have a more custom UI for adding subscriptions to a cart, you'll need to modify that UI and code to support adding Shopify Subscription objects to the Shopify Cart.

  • The current beta supports a standard "Subscribe&Save" scenario. Meaning that you can define which % discount should be applied for which subscription plan you sell your products on.

  • Shopify Subscriptions work with the model that you can only have one delivery frequency per Subscription. Meaning that if people order varying frequencies in one cart, this will result into multiple Subscriptions. This is not something Firmhouse can influence, but we are working on changes in the Firmhouse My Account to make the end-user experience better.

Now without further a-due, let's get started!

Step 1: Choose a payment provider supported by Shopify Subscriptions

Your Shopify store needs to use a payment provider that is supported by Shopify to work with Subscriptions. The default and easiest from is to go with Shopify Payments. But you can review support for the other options here: Supported payment gateways for Shopify Subscriptions

Step 2: Create an account at Mollie and enable iDeal, Bancontact, and SEPA Direct Debit

Create an account at Mollie and request at least the payment options iDeal, Bancontact, and SEPA Direct Debit. If you already have a Mollie account you don't have to create a new account. You can use your existing account and site profile if you're already accepting payments via Mollie.

Enable iDeal and Bancontact for Mollie in your Shopify store

In your Shopify store, add the iDeal (The Netherlands) and Bancontact (Belgium) payment methods from Mollie. The following steps are for iDeal. Repeat the same steps for Bancontact to add it:

  1. In your Shopify store, go to Settings > Payments.

  2. Click the Search by provider tab.

  3. Click the Mollie - iDeal from the options to add it.

  4. Click Manage account, install the Mollie - iDeal app and follow the instructions to link your Mollie account and site profile.

  5. When you return to Shopify, make sure the iDeal toggle is turned on. And the Test mode toggle is turned off.

  6. Click Activate

Configure Mollie in Firmhouse

Configure your Mollie account and site profile as payment provider in Firmhouse.

  1. From the Firmhouse sidebar, under Settings go to Payments

  2. Choose Mollie from the payment provider options

  3. Enter your Mollie live API key that you can copy-paste from your Mollie dashboard under the [...] More > Developers menu.

  4. Click save

Step 3: Get the Firmhouse Shopify app installed on your store

If you don't have a Firmhouse project yet:

  • Ensure you're logged into your Shopify store.

  • Go to the Firmhouse app on the Shopify app store and click Install.

  • Verify and confirm the installation the Firmhouse app on your store. Once installed you will end up in the Firmhouse Portal and you can continue with the next steps.

If you already have a Firmhouse project:

  1. Get in touch with Firmhouse support so that we can do a sanity check together with you if your current project setup is compatible with subscriptions on Shopify. Then follow the following steps:

  2. In Firmhouse Portal, got to Apps in the sidebar and find the new "Subscriptions using Shopify" app and click Configure.

  3. In the Your Shopify Store Domain enter your store domain <yourstore>.myshopify.com

  4. Click Save

  5. Ensure you're logged into your Shopify store.

  6. Go to the Firmhouse app on the Shopify app store and click Install.

  7. Verify and confirm the installation the Firmhouse app on your store. Once installed you will end up in the Firmhouse Portal and you can continue with the next steps.

Step 4: Create your desired subscription Plans in Firmhouse

In Firmhouse you can go to Plans from the sidebar. On this page you can define the various shipping frequencies you would like to offer to your subscribers. For example add an "Every 2 weeks" and "Every 4 weeks" or "Every month" and "Every 2 months" plan.

You will also be able to choose a "discount percentage" per plan that will be used to determine the price for products that get purchased with the selected shipping frequency.

Important: if you make changes to these percentages later, you'll need to re-sync your subscription plans with Shopify, more information about that below.

These are the plans that your customers will be able to choose from when adding products to their cart and when they are managing their subscription from the My Account page.

Step 5: Create or sync your products from Shopify to Firmhouse

Firmhouse needs to know which of your Shopify products and variants you want to offer on subscription. So you need to create and link them manually. Or you can use our Shopify Product sync to get a large chunk or all your products from your Shopify catalog into Firmhouse in one go.

πŸ’‘ If you're just starting with the implementation, it may make sense to manually create/sync only one or two products to Firmhouse to get the whole end2end Cart to Checkout flow up and running. If that works, you can put in the work to add your whole product catalog to Firmhouse.

Every product that you want to offer on a subscription needs to have the setting under Logistics set to On customer charge day.

When using the Shopify product sync this can be done by adding the tag FIRMHOUSE_SHIPMENT_ON_BILLING_CYCLE to your products in Shopify which you will import in Firmhouse.

Step 6: Sync the subscription plans to Shopify

  1. From the Firmhouse sidebar, go to Apps.

  2. Find the Subscriptions using Shopify app and click Configure.

  3. In the app configuration go to the Sync tab.

  4. Click Sync now.

Products and plans are now created in your Shopify store and you can start with adding the "Add subscription to cart" interface on your product detail pages in the next steps.

Step 7: Add or build subscription options on your product detail pages

Now it's time to add the subscription options to your product detail pages, so your customers can add them to their cart. There are two ways to do this:

  1. Add the standard Firmhouse Subscription Options widget. (for Shopify 2.0 supported themes)

  2. Build or modify your existing subscription widget.

7A: Add the standard Firmhouse Subscription Options widget

  1. In your Shopify store, go to your Online Store sales channel.

  2. Find your theme and click Customize to open the theme editor.

  3. In the theme editor, select the Product template page you want to edit by finding it via the dropdown on the top of the screen. For example: Products > Default product

  4. In the sidebar under Template in the Product information click Add block.

  5. Switch to the Apps tab in the Add block mini-UI and add click Subscription Options. This adds the Firmhouse standard subscription options to your page.

  6. You can drag-drop the widget in the right position and customize a few styling items.

7B: Build or modify your existing subscription widget

There are a lot of ways for theme developers to build custom user interface on product detail pages. Building a custom subscription widget is not so much related to Firmhouse, but you rather need to utilize the standard Liquid tags and development methods that Shopify offers for this.

But we will provide some pointers and general directions here. And we'll keep improving this section as we learn about specific implementation struggles that developers may have.

Basic principle: Make sure a Selling Plan is added to the cart

Firmhouse will create Selling Plans in Shopify for the products that you want to sell on subscription. Selling Plans are something native to Shopify. To be able to Checkout a subscription, a Selling Plan for a product needs to be added to the cart.

Thus, your subscription widget should ultimately take care of having a hidden input field or a radio button that sets the name="selling_plan_id" as part of your "add to cart" form. This way the appropriate selling plan gets added to the cart.

Take a look at the following two guides to learn how in Liquid you can fetch the available selling plans on a Product Detail Page, and how you may use the attributes of a selling plan to build a user interface on your product detail pages:

Step 8: Add Checkout Button for iDeal/Bancontact or a Checkout Widget for Local Payment Methods

Because Shopify does not yet have the proper technical support for iDeal, Bancontact, and SEPA as part of Shopify Payments, additional configuration is needed to support these payment methods. These options ensure that Shopify Checkout is set to a special "iDeal/SEPA mode," enabling a SEPA direct debit mandate to be generated after payment and scheduling recurring orders.

Depending on your Shopify plan, you can:

  • Add a special checkout button for iDeal and Bancontact on your cart page.

  • Add a checkout widget for local payment methods, allowing switching between iDeal and card (available only for Shopify Plus).

Choose the option that aligns with your Shopify plan to provide seamless payment support.

8A: Add a Special Checkout Button for iDeal and Bancontact

If you are not on Shopify Plus plan, your customers will have to check out via a separate button from the cart page for iDeal, Bancontact, and SEPA. This button will still link to Shopify Checkout so everything stays native. Firmhouse ensures that Shopify Checkout is set to a special "iDeal/SEPA mode," enabling a SEPA direct debit mandate to be generated after payment and scheduling recurring orders.

To learn how to add a special "Checkout with iDeal/SEPA" button in your theme, please review the following guide on the Firmhouse Developer Docs: Customizations for using SEPA based payment methods during checkout

8B: Add Checkout Widget (Shopify Plus)

If you are on a Shopify Plus plan, you can add a custom checkout widget directly to your cart. This widget, called the "Local Payment Method Switcher," allows your customers to toggle between two payment options during checkout:

  1. Local Payment Methods like iDeal and Bancontact.

  2. Regular Payment Methods such as credit cards and PayPal.

Follow these steps to integrate the "Local Payment Method Switcher" app block:

  1. From your Shopify admin, go to Settings > Checkout.

  2. In the Configurations section, click Customize next to the checkout configuration that you want to edit.

  3. In the checkout and accounts editor, ensure that the Checkout page is selected, and click the apps icon to access the Apps sidebar.

  4. Click the βŠ• Add app block button next to "Local Payment Method Switcher."

  5. In the popup, select Checkout to add it to the page.

  6. Customize the widget as needed.

  7. Click Save.

This allows you to integrate Firmhouse's subscription options and enable payment methods like iDeal and Bancontact directly in your checkout flow.

Step 9: Done! 🀩

Go to your store, add a subscription option to the cart, and enjoy checking out the subscription products with Credit Card, PayPal, iDeal, or Bancontact. The subscription should appear in the Customers overview in the Firmhouse Portal shortly after.

🧐 Of course we understand that reading and trying to follow this guide can be a bumpy road. If you're stuck on something or have a question.

Don't hesitate to reach out to our excellent support team! During the Private Beta period we'll give extra care from our engineers to help you with your Shopify Native Checkout problems.

Did this answer your question?