Managing subscription changes & cancellations

When your customers’ needs evolve, they’ll need to move between plans. Whether they’re scaling up, adjusting their feature set, or unfortunately canceling, Mantle makes these transitions straightforward for both you and your customers.

Types of subscription changes

Mantle supports several types of subscription modifications, each with its own timing and billing implications:

Upgrades

When customers move to higher-value plans with more features or higher limits. Think of upgrades like extending your service level in the middle of a contract - the difference in price is charged immediately for the remaining time until the next billing date.

Downgrades

When customers move to lower-value plans with fewer features or reduced limits. Unlike platforms that delay downgrades until the end of the billing period, Mantle processes them immediately and converts the unused portion into app credits for future use.

Plan switches

When customers move between plans of similar value but different focus. This is perfect for when customers realize they need a different feature set rather than simply more or less of what they already have.

Performing subscription changes

You have flexibility in how you handle subscription changes - whether through Mantle’s admin interface or by building the functionality directly into your app.

Using Mantle’s admin

The admin interface is ideal for manually processing changes, particularly for sales-assisted conversions or special circumstances:

1. Find the customer in the Mantle admin
2. Navigate to their subscription details
3. Select Actions → Request plan change
4. Select the new plan from the dropdown
5. Copy the confirmation URL to send to the customer

This generates a approval URL that you can send directly to the customer, allowing them to review and approve the change.

Using Mantle’s API

For automated changes or integration into your own systems:

1. Call the subscriptions endpoint with the customer ID and new plan ID
2. Mantle recognizes the customer already has a subscription
3. The system processes the change and returns a confirmation URL
4. Redirect the customer to the confirmation URL for approval

The same API endpoint that creates subscriptions also handles changes - Mantle automatically detects existing subscriptions and processes the modification instead.

Self-service implementation

Many apps prefer to give customers direct control over their subscription level:

1. Create a plans page in your app that displays available plans
2. When a customer selects a new plan, call Mantle’s subscriptions endpoint
3. Redirect the customer to the returned confirmation URL
4. Mantle processes the change after customer approval

This approach puts control in your customers’ hands while maintaining the required Shopify approval flow. It’s particularly effective when combined with usage metrics that help customers understand when they should upgrade.

Cancellations

Despite your best efforts, some customers will eventually cancel their subscriptions. Mantle provides straightforward tools to handle this part of the subscription lifecycle.

Using Mantle’s admin

For manually processing cancellations:

1. Find the customer in the Mantle admin
2. Navigate to their subscription details
3. Select Actions → Cancel subscription

4. Enter the customer’s name to confirm cancellation
5. Specify the reason for internal records

Capturing cancellation reasons is particularly valuable for improving your product and addressing common concerns that lead to cancellations.

Self-service cancellations

Many apps also implement self-service cancellation to simplify the process for customers:

1. Implement a cancellation flow in your app
2. Use the DELETE method on the subscriptions endpoint with the subscription ID
3. The system will process the cancellation

For more details on implementing any of these subscription features in your app, refer to our API documentation.