Subscription management

Use the Subscription engine to manage customer subscriptions, modify billing cycles, process refunds, and handle payment failures through the Support Tool.

​

Subscription management

To manage subscriptions:

1. Go to the Support Tool page.
2. Search for a user or click on the User UUID under Latest payments.
3. You will see sections with the following user details:

• User information: Shows user IDs, email address, user agent (browser), IP address, and creation date.
• Payments: Shows transactions and refund options.
• Subscriptions: Performs subscription management actions and shows subscription status.
• One-off: Shows lifetime subscription access.
• Webhook events: Shows events related to the user. Learn about Subscription engine webhook events.

​

Modify subscriptions

From the Subscription section, you can perform the following actions:

​

Subscription status

To check a user’s subscription status, open the User Information page in the Support Tool. The Subscription section shows two key fields that tell you the current state and what happens next:

• Status
• Next check

​

Status

The status field shows the current subscription state:

• INTRO: The subscription is in its trial period.
• RECURRING: The trial is over and the subscription is active. Charges occur 2 hours before each billing cycle to ensure uninterrupted access.
• AUTORENEW_OFF: Auto-renewal is disabled. The subscription will end after the current period.
• PAUSED: The subscription is paused until a set date. Premium access is unavailable during this time.
• GRACE: Payment failed, but the user still has temporary access.
• RETRY: Payment failed and the system is retrying the charge.
• EXPIRED: The subscription has ended.

The is_active webhook property is true when premium access is active, and false when it’s disabled.

​

Next check

The next_check field shows when the next subscription action will occur. What happens depends on the current status:

​

Track status changes

Track all subscription status changes to maintain your own analytics and stay up-to-date on user activity. Each status change creates an event that you can view in two places:

• In the Webhook Events section on the user’s information page in the Support Tool.
• At your backend via webhook (if configured).

Learn more about Subscription engine webhook events.

​

Subscription migration

You can switch an active subscription to a different Price Point (subscription plan) using POST /subscription/migration API endpoint or directly from your Support Tool. To process migration in the Support Tool:

1. Go to the Subscriptions section of the User Information page.
2. Set up migration fields next to the Migrate button:

• Price Point to migrate to.
• Migration strategy:
  • price_prorate: Unused time is credited toward the new plan’s first payment.
  • delayed_start: Unused time is converted to a free trial on the new plan.
• Dry Run: Enable to preview charges without executing the migration.
• Reason: Short reason code.
• Comment: Human-readable comment or reference (e.g., support ticket link).

3. Click Migrate.

​

How migration strategy works

By default, if you select a migration strategy that can’t be applied to the specific scenario, the API returns a 400 error. You can set strict_mode to false in the API request to automatically switch to the appropriate migration strategy when the selected one fails. The strict_mode parameter defaults to true. Here are scenarios where the selected strategy would fail:

​

One-off

To check if a user has been granted lifetime access, go to the One-off section. Lifetime access is permanent and can only be revoked if a full refund is issued.

​

Payments

The Subscription engine handles payments end-to-end and includes built-in deduplication to prevent duplicate charges when users attempt to purchase a product they already own.

​

One-click payment

Once a customer completes a purchase, their payment credentials are securely stored. This allows one-click payments for future purchases without re-entering details. This feature works for both one-off and subscription upsells, streamlining the checkout experience.

​

Refunds

To process a refund, click any transaction under the Payments section. Subscription engine supports the following refund types:

• Full Refund: Entire amount refunded; subscription immediately becomes EXPIRED, one-off payment is revoked.
• Partial Refund: Partial amount refunded; auto-renewal is disabled automatically.
• Soft Refund: Funds are refunded, but auto-renewal remains enabled. No effect on subscription or one-off purchase.

When processing a refund, you can use additional fields:

• Reason: Short reason for the refund.
• Comment: Custom support engineer comment (Jira task ID, ZenDesk ticket ID, etc.).

​

Free trials

To launch a free trial, you need to save the user’s payment information without charging their card. This is done through the Primary Workflow with the proper metadata configuration.

1. Create a client session with the special metadata flag ff_auto_cancel = true.
2. The Primary Workflow processes this flag:
   • The card is authorized like a normal payment.
   • Instead of completing the transaction, Primer cancels it.
3. Result:
   • No charge is made and no funds are withdrawn.
   • The card data is saved for the first subscription renewal.

This ensures the card is valid and prevents losses during future automatic charges.

​

Payment method update

When a user has failed payment attempts and all retry stages are unsuccessful, you can direct them to an Update Payment Method page. This page can also be used anytime card information needs updating. How it works:

• The user goes to a page that looks like a standard payment form
• It uses a special update_payment_method function designed only for card updates, not purchases
• When entering a new card, authorization without charging is performed:
  • The transaction is cancelled immediately after authorization
  • The card data is saved for future charges

​

Disputes

When a dispute is initiated for any payment, the system automatically responds to minimize financial and reputational risks:

• Auto-renewal is disabled immediately upon receiving a dispute
• Assumptions:
  • The dispute will be automatically resolved in favor of the user
  • Funds from the last transaction will be automatically refunded by the PSP
  • No new subscription charges will be made, preventing future disputes

​

Retries

When a renewal charge fails, the system automatically starts retry attempts. This helps preserve subscriptions and reduces customer churn. Each recovered subscription continues generating revenue.

​

Long (Smart) Retry schedule

For subscriptions with 7-day intervals or less:

• Day 0 (billing problem detected): Activate grace period
• Day 2: Partial charge (70%)
• Day 7: Partial charge (50%)

For subscriptions with 31-day intervals or less:

• Day 0 (billing problem detected): Activate grace period
• Day 2: Full charge
• Day 7: Full charge, deactivate grace period
• Day 12: Partial charge (70%)
• Day 20: Partial charge (50%)

For subscriptions with intervals greater than 31 days:

• Day 0 (billing problem detected): Activate grace period
• Day 2: Full charge
• Day 7: Full charge, deactivate grace period
• Day 12: Full charge
• Day 22: Partial charge (70%)
• Day 33: Partial charge (50%)

​

Short Retry schedule

For subscriptions with 7-day intervals or less:

• Day 0 (billing problem detected): Activate grace period
• Day 2: Partial charge (70%)

For subscriptions with 31-day intervals or less:

• Day 0 (billing problem detected): Activate grace period
• Day 7: Partial charge (70%), deactivate grace period
• Day 20: Partial charge (50%)

For subscriptions with intervals greater than 31 days:

• Day 0 (billing problem detected): Activate grace period
• Day 7: Full charge, deactivate grace period
• Day 15: Partial charge (70%)
• Day 33: Partial charge (50%)

​

Next steps

Understand webhook events sent by the Subscription engine.