Skip to main content

Documentation Index

Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt

Use this file to discover all available pages before exploring further.

Plan Builder is the section of Meridian where you design the pricing structure of your Shopify app before going live. Instead of hard-coding plan logic into your backend or managing billing state manually, you define your plans, the features each plan unlocks, and the lifecycle events that fire as merchants subscribe and cancel — all in one place. Meridian then connects this structure to the Shopify billing API so your app charges merchants correctly from day one.

​
Why plan structure matters early

Shopify’s billing API requires that every recurring charge be tied to a specific plan. If you ship your app without a clear plan structure, you’ll end up retrofitting billing logic after merchants are already using your product — which means potential breaking changes, confused merchants, and lost revenue. Plan Builder helps you get this right before you submit to the App Store.
Design your plans in Plan Builder before you write billing integration code. The plan names, prices, and trial periods you configure here map directly to the RecurringApplicationCharge objects Shopify creates when a merchant accepts a subscription.

​
The three sections of Plan Builder

Plan Builder is organized into three tabs: Plans, Features, and Events. Together they define the full billing model for your app.

Plans

Create and manage your subscription tiers — name, price, trial period, and which Shopify store types can access each plan.

Features

Define capabilities that vary between plans. Attach features to plans so merchants understand what they get at each price point.

Events

Track custom lifecycle events that fire when billing state changes, such as plan acceptance, activation, or cancellation.

​
Plans

​
Creating a plan

Navigate to Plan Builder → Plans and click Create Plan. Fill in the plan details:
FieldDescription
Plan NameThe public-facing name merchants see in the Shopify billing prompt (e.g., Basic, Pro, Enterprise).
DescriptionOptional text that explains what this plan includes.
Price (USD/month)The monthly price in US dollars. Must be greater than $0.00.
Trial Period (days)Optional free trial before billing starts. Leave empty for no trial.
AvailabilityWhich Shopify store plan types can see and activate this plan.

​
Store plan availability

Shopify categorizes merchant stores into plan types. You control which types can access each of your pricing tiers using the Availability setting.
ValueLabel
allActivated for all the stores
Select Activated for all the stores (all) to make a plan available to every merchant regardless of their Shopify subscription. Selecting all overrides any other availability selections.

​
Editing and deleting plans

Click Edit on any plan card to open its detail form. Make your changes and click Save. To remove a plan, open it for editing and click Delete — you’ll be asked to confirm before the plan is permanently removed.
Deleting a plan removes it from all feature and event assignments. If merchants are actively subscribed to a plan you delete in Meridian, their Shopify billing charges are unaffected — but you should handle that gracefully in your app logic.

​
Features

Features represent the capabilities of your app that vary between pricing tiers. By mapping features to plans, you give merchants a clear picture of what they get at each price point, and your app can use these definitions to enforce entitlements at runtime.

​
Feature types

Every feature has one of two types:
TypeBehavior
booleanA capability that is either enabled or disabled for a plan (e.g., “Custom Domain”, “API Access”).
numberA numeric quota that varies per plan, with an optional upper limit (e.g., “API Requests per month”, “Storage Limit in GB”).

​
Creating a feature

Go to Plan Builder → Features and click Add Feature.
1

Name your feature

Enter a display name that merchants will recognize, such as API Access or Monthly API Requests.
2

Write an optional description

Add context about what the feature controls. This helps your team and improves the plan comparison UI in your app.
3

Choose the feature type

Select Boolean for on/off capabilities, or Number for quota-based limits.
4

Set a default value

For boolean features, choose whether the feature is enabled or disabled by default. For number features, enter a starting value and an optional maximum limit.
5

Assign to plans

Open each plan you want to include this feature in, and toggle it on. For number features, override the default value per plan as needed.

​
Assigning features to plans

When creating or editing a plan, scroll to the Select Features section. Toggle each feature on or off. For number type features that are enabled, you can set the specific value for that plan — overriding the feature’s default. 
Basic Plan  →  API Access: ✓  |  Storage Limit: 10 GB  |  Custom Domain: ✗
Pro Plan    →  API Access: ✓  |  Storage Limit: 50 GB  |  Custom Domain: ✓

​
Events

Events let you track and respond to billing lifecycle milestones within your app. You define events in Plan Builder, assign them to plans, and then use their keys in your app’s backend to trigger logic when billing state changes.

​
Creating an event

Go to Plan Builder → Events and click Add Event.
  • Event Name — a human-readable label (e.g., Subscription Activated).
  • Event Key — a unique identifier in lowercase with underscores (e.g., subscription_activated). Your app uses this key to identify the event programmatically.
Event keys must contain only lowercase letters, numbers, and underscores. Meridian enforces this automatically as you type.

​
Assigning events to plans

When creating or editing a plan, scroll to the Select Events section. Toggle each event that applies to that plan. This lets you configure plan-specific event handling — for example, firing a different webhook on plan cancellation depending on which tier the merchant was on.

​
Shopify billing event types

Meridian’s analytics and CRM features track the full set of Shopify Partner API event types. Understanding these helps you design your event configuration and write the correct backend handlers.

​
Subscription events

Event typeDescription
SUBSCRIPTION_CHARGE_ACCEPTEDThe merchant accepted the billing prompt and the charge was created.
SUBSCRIPTION_CHARGE_ACTIVATEDThe recurring charge became active and billing started.
SUBSCRIPTION_CHARGE_DECLINEDThe merchant declined the billing prompt.
SUBSCRIPTION_CHARGE_EXPIREDThe charge expired before the merchant accepted it.
SUBSCRIPTION_CHARGE_CANCELEDThe merchant canceled their subscription.
SUBSCRIPTION_CHARGE_FROZENThe subscription was frozen (typically because the merchant’s Shopify account is paused).
SUBSCRIPTION_CHARGE_UNFROZENThe subscription resumed after being frozen.

​
One-time charge events

Event typeDescription
ONE_TIME_CHARGE_ACCEPTEDThe merchant accepted a one-time charge.
ONE_TIME_CHARGE_ACTIVATEDThe one-time charge was activated and completed.
ONE_TIME_CHARGE_DECLINEDThe merchant declined the one-time charge prompt.
ONE_TIME_CHARGE_EXPIREDThe one-time charge expired before being accepted.

​
Relationship events

Event typeDescription
RELATIONSHIP_INSTALLEDA merchant installed your app.
RELATIONSHIP_UNINSTALLEDA merchant uninstalled your app.
RELATIONSHIP_REACTIVATEDA merchant who previously uninstalled your app reinstalled it.
RELATIONSHIP_DEACTIVATEDThe app was deactivated for a merchant.

​
Tips for designing good pricing tiers

Three tiers (e.g., Starter, Growth, Pro) is the most common and most effective structure for Shopify apps. One tier anchors low expectations, one captures the majority of revenue, and one exists for merchants who need everything. Avoid fewer than two or more than four.
Choose a pricing metric that grows as your customers succeed. Order count, products synced, or API calls are all good metrics. Flat features without usage caps are harder to justify upgrading.
Shopify merchants are hesitant to commit to paid plans without trying first. A 7–14 day trial on your top two tiers significantly reduces friction at install time and increases activation rates.
Use boolean features to gate capabilities that power users need but free-tier merchants don’t. This gives you a clear upgrade hook. Examples: custom branding, priority support, advanced reporting, API access.
For number-type features, set limits that are generous enough that small merchants don’t feel penalized, but low enough that power users want to upgrade. Err on the side of generosity — it reduces churn.
Last modified on May 5, 2026