What is the theme engine? How to empower your customers via the customer portal

Creating a rich customer experience has always been at the core of Recharge’s beliefs. Merchants have long sought a way to increase functionality and flexibility for the customer without the added stress of unnecessary developer time or frustration. Running a business is difficult enough, but worrying about how a customer might interact with your brand if they need to adjust their next shipment shouldn’t be a place where too many resources are needed.

When the Recharge app was first launched, it came equipped with a fully functional, feature rich customer portal right out of the box. This created a unique experience whereby all the features a customer would need to manage their own subscription were packaged together in one place. But sometimes that might not be enough, a client might want custom functionality, removal of clutter, or a complete redesign of the UI.

We know all merchants are different and some need advanced editing capabilities within the customer portal. Therefore, if the standard customer portal isn’t enough, we opened up the Recharge API as an additional option for experienced developers to customize their builds of the portal. This gave you the option to break down the customer portal entirely and rebuild it to match the customization you need. The freedom was unlimited but the scope was generally too big for most merchants to handle.

With that in mind, we got to work developing a third option for the customer portal, something of a middle ground between the standard portal and requiring advanced API knowledge. As of September of 2019, we’ve launched the Theme Engine.

In this article, we’ll dig into the differences between the three distinct options for customizing the customer portal and provide examples and use cases for each. 

What is the theme engine?

By default, all merchants have access to the Standard Portal. This is a Recharge hosted customer portal that allows enabling/disabling of specific features via the Recharge Admin UI. The Recharge Theme Engine allows developers to expand the Standard Portal, while still being hosted by Recharge. If a merchant needs to modify the portal beyond CSS changes but not enough to warrant use of the API, the Theme Engine is the solution. While an advanced developer is still necessary (knowledge of HTML, CSS, JavaScript, etc), the Theme Engine allows direct editing and customization of the customer portal page source code directly.


Both the Theme Engine (Recharge hosted customer portal) and the API (Independently hosted customer portal) are mutually exclusive, but function in a similar way.

Each of the three options – standard portal, Theme Engine, and API – have separate advantages and limitations. If you’re interested in discerning the variations for yourself, check out the Theme Engine documentation and API documentation.

As a general overview, the following chart will show the major advantages and limitations of each option. Later, we’ll walk through each in detail so you can make the best decision for your build:

pros and cons

Note: In order to use the Theme Engine, merchants need to upgrade to a Recharge Pro plan.

Standard portal

Old Pine Candle Co uses the standard out-of-the-box customer portal with no modifications of any kind.

Recharge’s standard customer portal is fully functional and gives Shopify merchants everything they need to get up and running. Depending on the permissions given to customers through the Recharge dashboard, those customers can modify delivery addresses, skip or cancel shipments, change payment methods and more on their own without the need to reach out to a store’s customer support team.

Agencies and developers can customize the look and feel of the portal with HTML, CSS and Javascript. All custom code is added to the Customer Portal settings page in the Recharge dashboard. For more information, read the knowledge base article on modifying CSS in the Customer Portal here.

Edit code within the Recharge app to modify the existing customer portal.

The standard customer portal is useful to provide a base level of functionality or before a decision is made to invest in an upgrade. All of the functionality is there, and the standard portal provides all of the core functionality to support the subscription management experience. It’s perfect for merchants that are either in the beginning stages of their subscription business or looking for a rapid launch followed by iterative development.

While the standard portal is great for a store to hit the ground running, it has several limitations. The page structure and functionality cannot be modified and CSS and JavaScript can only be added to the headers and footers of the customer portal.

thryve checkout
In the previous example, The Old Pine Candle Co. uses the standard Customer Portal with no additions. In this example Thryve uses the standard Customer Portal as well but has added a touch of HTML and CSS. Both include the functionality needed for their respective merchants but the look and feel is different due to the style changes.

The standard portal shows its limitations if a merchant wants to modify it beyond skin-deep style changes. In order to add custom UI, integrate third-party apps, or a third feature, your store would need to upgrade your plan to access the Theme Engine.

Before we move on: we’ve written articles in the past about the business case for investing in upgrading your customer portal. In this article, we’re purely laying out the differences between the three options. For more information on why you may want to upgrade including diving into potential increases in average order value, lifetime value, retention, and more crucial key performance indicators, read more here.

Theme engine

The Theme Engine was built to allow developers and agencies to customize the interface of the Customer Portal. With the Theme Editor, Theme Engine’s code editor, it is possible to tailor the look and feel of the portal to fit the store’s style and branding. If you need more depth, next up from the standard customer portal is the Recharge Theme Engine.

Using the Theme Engine, developers and agencies can modify the structure and layout of the portal. Options include but are not limited to: collapsing multiple pages together to add a custom product flow, adding in animations to further guide customers, and more.

Coding becomes much easier as well. While it is still required to have an experienced developer, the Theme Engine breaks down the HTML into separate files making it far simpler to target individual elements. There are included sample template files as well to hit the ground running.

tiege hanley checkout on recharge

Tiege Hanley uses the Theme Engine for their customer portal. In their particular case, they decided to trim away many of the optional elements to make managing subscriptions as simple as possible for their customers. The result is a very clean UI with a dark color scheme that allows your eyes to focus on the features they want you to focus on. This makes the UX very straightforward with as little confusion as possible.

dr axe checkout on recharge

The Dr. Axe customer portal is an example of adding additional functionality to the Theme Engine. They operate an independent server which allows them to make and process API calls outside of the Theme Engine.

Note: The Theme Engine is limited to template logic and variable edits, complex operations and calculations are a great use case for the API.

For example, this server, or middleware, allows Dr. Axe to make API-triggered calls to Loyalty Lion (their loyalty and rewards solution), which lets customers seamlessly view reward points from their previous purchases and apply them towards their next subscription.

These changes allow Dr. Axe to enhance subscriber engagement beyond what Recharge alone can provide, by giving out reward points for each dollar spent, encouraging subscribers to keep coming back, and keeping them within the customer portal experience.

With creative enhancements like this, Customers are incentivized to return, spend their points, increase their LTV, and improve overall customer satisfaction – all on their own!

Although the Theme Engine is a major feature improvement from the standard customer portal, there are a few limitations. While it’s much more flexible, it is important to mention again that the Theme Engine is not compatible with any API calls unless you have a middleware server you run on your own backend. Additionally as mentioned above, the Theme Engine is still a developer’s tool; to make the most of this tool, developers should be familiar with building Shopify themes from scratch.

If you’re looking at adding new functionality, making multiple API calls, or integrating with third-party apps, then it’s time to use the API.


Using the Recharge API, developers have the ability to create a new customer portal. It is possible to add functionality from third-party integrations, collapse pages, or even wipe the slate entirely clean and build a brand new portal from the ground up on your own terms.

Note: Recharge does not offer a baseline customer portal product with the API. If this is the option you choose, you must build an entire customer portal from scratch.

Building your portal using the API allows for full customization – both from Recharge and third-party integrations. Using the API, you can implement custom functionality like creating a ‘skip all’ button for customers with multiple subscriptions to skip a month on all of them at once, or perhaps add in custom One-Time Product support so those same customers can try out additional products without committing.

atlas coffee on recharge checkout

Atlas Coffee built out their customer portal using the API. Not only did they combine everything into one page, but they also went further and introduced rewards as well as their own ‘Coffee Passport’ section that tells the story of where that month’s coffee originated from. The additional functionality, pulling the coffee ‘passport and rewards, can only be accomplished with the API.

native checkout

By recommending complementary products within the customer portal, Native drastically increases cross-sell and upsell add-ons to existing subscriptions. This increases average order value and customer lifetime value, while decreasing subscription cancellations as customers are able to swap to a product they like better rather than outright canceling.

battlbox checkout on recharge

Battlebox utilizes the API to customize their portal and add rewards to the dashboard. They make social referrals seamless by adding a widget to share a customer’s purchase on social media for additional rewards.

The API is the end-all-be-all in terms of sheer flexibility and options, but with that power comes a cost – it is the most resource intensive of the three options. If you’re currently using Theme Engine but need some of the custom functionality that comes with the API, you will need to upgrade to the API and disable Theme Engine.


The post-purchase customer experience is just as important, if not more so, than the initial checkout in a subscription-driven business model. The opportunity to fight churn, increase AOV and LTV, and grow customer engagement lives and dies in the customer portal.

At a glance, the standard portal, Theme Engine, and API all perform similar functions. As we’ve discussed, there is a lot more going on under the surface.

There are a variety of options available to bring your customer portal builds to life, each with their own pros and cons. While the decision may not be one-size-fits-all, we hope to provide you with the resources to pick the most effective one for your use case. If you’re looking for more inspiration, check out the Customer Portal Showcase for a growing selection of our top merchants that use the Theme Engine and API. If you’re looking for a developer resource to build out your customer portal team, please reach out to our support team.