Recharge and subscription apps

Toki rewards subscription sign-ups and renewals from the orders your Shopify store already sends it, so you can reward subscribers without connecting your subscription app at all. Connecting Recharge or Stay.ai goes further: your membership tier and spending discounts follow customers onto their active subscriptions, Toki's discount codes work in Recharge, customers are signed in to Toki from the Recharge customer portal, and the wallet can list a customer's Stay.ai subscriptions.

What works without connecting anything

Toki treats an order as a subscription order when any item on it was bought with a subscription purchase option (a selling plan) in your Shopify store. That is all the subscription reward activities look at, so it makes no difference which app sells the subscription: Recharge, Stay.ai, or any other app that sells through Shopify's purchase options is covered the moment the order reaches Toki.

Smartrr and Skio appear on the Integrations page marked Installed, with a Guide action and nothing to fill in. There is no connection to set up for them.

Reward subscription sign-ups and renewals

The reward catalog has a Subscription group with two activity types:

Activity	What customers earn it for
Sign up for Subscription	Starting a subscription. Each customer earns it once, on their first subscription order. A later subscription order does not earn it again.
Subscription Continuation	Keeping a subscription going. Customers earn it every time they complete the number of orders you set.

Create the reward

Open Loyalty.
In the Ways to Earn section, click Add new activity.
Pick Sign up for Subscription or Subscription Continuation from the Subscription group.
Choose what customers get in the Reward card and set the Rules card (see below).
Set Status to Active and click Save.

The reward page works like any other reward: see Create and manage rewards for the rest of the cards.

Rules for subscription activities

Setting	What it does
Purchases of which products will be rewarded?	Of any product rewards every subscription order. Only of some products rewards orders that include at least one of the products you pick in Select matching products. Only of some collections of products does the same for the collections you pick in Select matching collections; this option is available for Sign up for Subscription.
Collection Page URL	Shown when the activity is limited to products or collections. It is where the wallet sends a customer who clicks Complete on this activity. Leave it empty and the wallet sends them to your store's home page.
Number of Orders	Subscription Continuation only. The number of orders a customer completes to earn the reward: "Customers will get the reward every time they complete the number of orders specified here." Use the Limits card to cap how many times a customer can earn it.

For Subscription Continuation, Toki checks the activity each time a subscription order arrives and grants the reward every time the customer completes the number of orders set in Number of Orders. If you limited the activity to products, only orders that include those products count.

Both activities are purchase rewards, so they share the behaviors of purchase reward rules: completions are approved automatically, the Discounts rules section decides whether orders that used a discount code still count, and a refund or cancellation takes the reward back the same way.

To give points on every subscription order instead, use a Points for purchase reward with Purchase type set to Subscription.

Connect Recharge

With Recharge connected, Toki:

creates every discount code it issues in Recharge as well, so customers can use their Toki codes on subscription orders,
attaches membership tier discounts and spending discounts to a customer's active subscriptions (see Carry discounts onto subscriptions below),
signs customers in to Toki when they open the Recharge customer portal (see Show Toki in the Recharge customer portal below).

Toki matches customers between the two systems by email address, so a customer's email in Recharge needs to be the one on their Toki member profile.

Create an API token in Recharge

In the Recharge merchant portal:

Open Tools & apps and click API tokens. Only the store owner can see this page by default; the owner can grant other staff accounts access to it. The first time, Recharge asks you to accept its API Terms of Service before you can create a token.
In the Admin tokens section, click Create new.
In Token details, give the token a name and a contact email.
For each permission, choose No access, Read access, or Read and Write access. Toki creates and updates discounts and subscription addresses, and reads your store details and customers, so give it Read and Write access for discounts and addresses and at least Read access for customers and your store.
Tick the checkbox in the Terms of service section and click Save.

To change the permissions later, click the token's name on the API tokens page to open the Edit API token page, adjust the Scope under each permission, and click Save.

After you save, click the token's name on the API tokens page to copy its value and its client secret.

Enter the token in Toki

In Toki, open Integrations.
On the Recharge row, click Install.
On the Install Recharge page, paste the token into API Token and the client secret into API Client Secret. Both are required.
Click Save.

Toki checks the token with Recharge before saving. If Recharge rejects it, the page shows Provided Api key is invalid or the required permission scope is missing, nothing is saved, and you can correct the token and try again. Once saved, the Recharge row shows the Installed badge.

Discount codes in Recharge

From then on, every fixed-amount, percentage, and free-shipping code Toki creates (for rewards, tier perks, spending, and referrals) also exists in Recharge, where it can be applied once, with the same expiry date. For membership discounts, the number of recurring payments the code applies to follows the Recurring discounts for subscriptions setting described below. Other codes apply to one payment, unless the reward has its own Custom subscription discount settings.

If you use a total code (the personal code that spends a customer's whole balance at once), Toki creates it in Recharge too, as a fixed-amount discount for the customer's balance, capped by the Max balance of your total code settings. When the balance changes, Toki removes that code from Recharge and issues a fresh one the next time the customer opens their wallet. A spending code that is refunded to the customer's balance is removed from Recharge as well.

Connect Stay.ai

With Stay.ai connected, Toki:

attaches membership tier discounts and spending discounts to a customer's active Stay.ai subscriptions (see Carry discounts onto subscriptions below),
can show a customer's Stay.ai subscriptions in their wallet (see Show Stay.ai subscriptions in the wallet below).

Toki finds a customer's subscriptions in Stay.ai by the email address on their Toki member profile.

Create an API key in Stay.ai

In Stay.ai:

Open Settings, then API Keys.
Click New API Key.
Fill in the Name, Description, and Email of the key's admin.
Under Scopes, give the key Read Subscriptions and Update Subscriptions. Toki reads subscriptions, adds and removes discounts on them, and creates customer portal links.

Enter the key in Toki

In Toki, open Integrations.
On the Stay.ai row, click Install.
On the Install Stay.ai page, paste the key into API Key.
Click Save.

Toki checks the key with Stay.ai before saving. If Stay.ai rejects it, the page reports Unauthorized, please check your Stay.ai API key and nothing is saved. Once saved, the Stay.ai row shows the Installed badge.

Carry discounts onto subscriptions

Two settings decide whether your loyalty discounts follow customers onto their active subscriptions in Recharge and Stay.ai. Both live on the Loyalty page, in the Subscription discount settings section. Change them and click Save in the bar at the top of the page.

Setting	What it does
Recurring discounts for subscriptions	How many payments a membership discount applies to: Limit discount to the first payment, Limit discount to multiple recurring payments with a Recurring cycle limit (2 or more), or Discount applies to all recurring payments. A membership reward with its own Custom subscription discount settings uses those instead.
Auto update subscription discounts	"Automatically updating customer subscriptions with membership discounts. If a non-membership discount is applied to the subscription, then the discount will not be updated."
Apply spending discounts to subscriptions	"Automatically apply spending discounts to the customer's latest active subscription."

Membership tier discounts

With Auto update subscription discounts on, a customer's tier discounts travel with their tier:

When a customer earns a tier, Toki redeems that tier's Discount code and Free shipping rewards for them and attaches the codes to each of their active subscriptions in Recharge or Stay.ai. Toki does this about a minute after the tier change, so a subscription started in the same checkout is included.
When a customer moves to another tier, the codes are swapped for the new tier's codes. When they hold several tiers at once, Toki uses the tier that comes last in the order you set with Reorder on the Memberships page.
When a customer leaves their last tier, the tier codes are removed from the subscription.

A subscription that already carries another discount code, including a Toki spending code, is left exactly as it is.

If you use Stay.ai, turning the setting on also runs a one-time pass over your active Stay.ai subscriptions, so subscribers who already hold a tier get their discounts right away. With Recharge, each subscriber's discounts are attached the next time their tier changes.

Spending discounts

With Apply spending discounts to subscriptions on, a discount code a customer gets by spending their balance in the wallet is applied to their latest active subscription in Recharge or Stay.ai, and the wallet tells them: "The discount code has been applied to your subscription. It will be used on your next order." If that subscription already has a discount code, the wallet says: "We couldn't apply the discount code to your subscription because another discount code is already applied." Either way the customer still gets the code itself to use at checkout.

Show Toki in the Recharge customer portal

When Recharge is connected, a customer who opens the Recharge customer portal on your store is signed in to Toki at the same time: a Toki module placed on a portal page shows their own balance, tier, and rewards, and the wallet launcher works there too, without a separate login. This applies to the customer portal that runs on your store's domain (Recharge's embedded portal). If the customer is not a Toki member yet, Toki creates their member account from their Recharge email the first time.

Recharge's guide for adding custom code to the portal covers the embedded portal, not the Unity portal theme. If you use Recharge's hosted portal, Recharge recommends switching to the embedded version.

A good fit for the portal is the Your Status module, which shows the customer's balance and progress toward the next membership. To place a module in the portal:

In Toki, open Design, click Edit on the module, and click How to show it on the website? in the top bar. Click Copy snippet to copy the module's HTML snippet. See Install modules on your storefront for the panel.
Recharge's guide for the embedded customer portal keeps custom code in your Shopify theme: in your Shopify admin, open Online Store, then Themes, open the actions menu (...) and select Edit code. In the Snippets folder, click Add a new snippet and name it recharge-custom-code.liquid.
Paste Toki's snippet into that file and save it.
The guide also has you add a short condition to theme.liquid so the snippet loads only on customer portal pages. This is a theme code edit; chat with us and we'll set it up with you.
Sign in to the portal with a test customer account to check the result. If you edited an unpublished theme, click Preview on the theme first and open the portal from the preview.

Show Stay.ai subscriptions in the wallet

With Stay.ai connected, the wallet can list a customer's active Stay.ai subscriptions with a button to manage them.

Open Design.
Click Edit on the Wallet module.
Open the blocks list for the screen where the subscriptions should appear, for example Home Screen Blocks, and click Add new item.
Set Block Type to Stay AI - Subscriptions Block.
Adjust the block's settings, then save and publish your design.

Setting	What it does
Block Title	The heading of the block. The default is Your active subscriptions.
Block Sub Title	A line under the heading, shown when the customer has subscriptions.
Container Image Visible and Container Image	Show an image in the block's header.
Perk Item Image Visible and Item Default Image	Show an image next to each subscription.
Show orders from all shops (for umbrella set-ups)	List the customer's subscriptions from every shop in your Toki account, not only the current one.

Each subscription shows its Next payment date, its items with their price and quantity, and its Total. A Manage Subscriptions button opens the customer's Stay.ai portal in a new tab. With Show orders from all shops on, each subscription gets its own Manage button instead, opening the portal of the shop it belongs to. A customer without subscriptions sees "You don't have any subscriptions yet."

Change or disconnect a connection

On the Integrations page, click Manage on the Recharge or Stay.ai row to replace the token or key, or Uninstall to disconnect. Uninstalling deletes the credentials from Toki. Discount codes Toki already created in Recharge, and discounts already applied to subscriptions, stay as they are in the other app. The subscription reward activities keep working either way. See Integrations and your API key for the Integrations page itself.