Subscribing customers

The moment when a customer decides to subscribe is important - it needs to be smooth, trustworthy, and seamless. Mantle provides flexible options for handling this significant transition from visitor to paying customer, regardless of whether they’re self-serving through your app or being assisted by your sales team.

Methods for subscribing customers

Subscriptions establish the billing relationship between your customers and your app. Mantle offers multiple methods to create subscriptions, each designed for different scenarios:

1. Self-service customer flow: Let customers select their own plan through your app’s interface (which uses the subscriptions endpoint behind the scenes)
2. Programmatically via API: Use Mantle’s subscriptions endpoint directly in your code for custom implementations
3. Using Mantle’s admin: Manually create subscriptions for specific customers, ideal for sales-assisted conversions

Each approach has its own advantages, but all ultimately use the same underlying subscriptions endpoint to ensure consistency in your billing and feature access.

Through your app’s plans page

For most apps, a self-service subscription flow provides the best customer experience. This approach is like having a digital storefront where customers can browse your offerings and make their selection.

A typical implementation involves:

1. Creating a plans page in your app that displays your offerings with clear features and pricing
2. Implementing a selection mechanism that captures the customer’s choice
3. Calling Mantle’s subscriptions endpoint when a plan is selected
4. Redirecting the customer to the confirmation URL for final approval

This self-service approach allows customers to browse and select plans directly through your interface, streamlining the subscription process while still using the same subscriptions endpoint that powers all Mantle billing.

Using the subscriptions endpoint directly

While many apps will implement a plans page with selection options, you can also call the subscriptions endpoint directly from your backend code. This approach is functionally identical to the plans page method but gives you more flexibility for programmatic implementations.

This direct approach is perfect for:

• Custom onboarding flows that integrate subscription creation with your app’s setup process
• Automated conversions from trials to paid plans without requiring additional user interaction
• Backend systems that need to manage subscriptions without user interface components

Here’s what happens when you call the endpoint:

1. Your app makes a request to Mantle’s subscriptions endpoint with the customer and plan information
2. Mantle creates the appropriate charge in Shopify’s billing system
3. Shopify generates a confirmation URL for the customer to review and approve
4. Mantle returns this URL to your app
5. Your app redirects the customer to this URL for approval

This approach gives you full control over when and how to initiate the subscription process within your application flow.

Using Mantle’s admin

For situations that require a human touch, Mantle’s admin interface provides a straightforward way to create subscriptions manually. This is particularly valuable for:

• Sales-assisted conversions where your team helps customers choose the right plan
• Special arrangements that might involve custom terms or plans
• Testing and troubleshooting when you’re implementing subscription features

To create a subscription through the admin:

1. Navigate to the customer’s profile in Mantle
2. Click the Actions dropdown
3. Select Create subscription

4. Choose the plan you want to subscribe the customer to
5. Specify a return URL (where the customer will be directed after approval)
6. Send the resulting confirmation URL to the customer

The manual approach gives you complete control over when and how the subscription is created, while still ensuring that the customer explicitly approves the charge as required by your payment platform. Behind the scenes, this method also uses the same subscriptions endpoint as the other approaches.

Handling subscription states

Once a customer subscribes, your app needs to adapt based on their subscription status. This affects everything from feature access to messaging within your interface.

Subscription states in Mantle

Mantle tracks several subscription states that your app can use to determine user access and experience:

• Subscribed: The customer has an approved, active subscription
• On trial: The customer is in an active trial period with temporary access
• Canceled: The subscription has been terminated, either by the customer or your team
• Frozen: The subscription is temporarily inactive because the store has been frozen

Understanding these subscription states helps you track your customers’ journey and provide the appropriate experience at each stage.