Manage Subscriptions

Customers make recurring payments for access to a product or service by subscribing to a plan. To subscribe to a product or service, customers need to provide more information about themselves so you can charge them recurrently.

Every customer subscription in MoneyHash needs to be linked to a previously created plan. This page first presents an overview of the subscription workflow in MoneyHash, describing all possible states related to the subscription workflow. After, you will learn how to manage subscriptions on MoneyHash and the available operations you have available.

Subscription in MoneyHash

When a customer subscribes to one of your business's plans, creating their subscription within MoneyHash's system is crucial. This action establishes a connection between the customer and the selected plan by using unique identifiers of both the customer and the plan. This process helps ensure that the customer receives the services they have subscribed to, and the business can keep track of the customer's subscriptions accurately.

Subscription creation process

To subscribe a customer to a previously created plan, use the Create a Subscription endpoint, providing the necessary data, such as the plan's unique identifier and the start date of this new subscription. Additionally, choose optional fields to customize each customer's subscription, overriding the plan's configurations. Furthermore, there is an option to set a card token with a flag, facilitating automatic charging
for the customer.

Charge automatically

The charge automatically is a configuration option that you can turn on for a customer's subscription to enable their billing cycle invoices to be paid automatically with a saved card.

Enabling automatic charging

To enable automatic charging, you need to create the subscription and add the charge_automatically property astrue and the primary_card_token with the saved card token. This will allow the payment to be executed at every invoice due date without further customer action.

As it happens automatically, the status flow will be cyclic, revolving to ACTIVE status.

Disabling automatic charging

If you don't set the charge_automatically property astrue, not activating the charge automatically function, the customer will need to execute a new payment in every new billing cycle manually. In this case, you will need to provide the customer with the URL to perform the payment.

The subscription will follow the flow presented below:

Subscription customization

When initiating a new subscription, you can customize the subscription, overriding the plan configuration. To customize the subscription, you need to provide an object within the customization parameter. This object allows you to tailor specific properties, providing a unique configuration for that individual subscription. Notably, these customizations remain exclusive to that particular subscription and do not impact the overarching plan or any other related subscriptions.

Customizable Properties

Amount: Modify the subscription amount exclusively for this subscription.
One-time Fee: Adjust, apply, or remove the one-time fee value as needed.
Trial Period: Customize the trial period duration for this subscription.
Recurrency: Toggle the recurrence status for this subscription.
Recurring Cycles: Fine-tune the number of billing cycles for this subscription.
Discount Amount: Alter the total discount amount for this subscription.
Discount Percentage: Modify the percentage discount for this subscription.
Discount Cycles: Adjust the number of cycles during which the discount is applied.

You can use the customization feature to deliver tailored offerings to your customers. Whether providing special discounts, adjusting plan prices, or making subscription-specific modifications, this functionality enables you to cater to individual customer needs precisely.

Dashboard

You can create and manage subscription through MoneyHash's dashboard as well.

Once a subscription is created, it will follow the workflow presented in the next section of this page, changing its status according to each scenario.

Subscription lifecycle

The status of the subscription defines the subscription lifecycle. The following workflow illustrates the different stages of the subscription. When a customer subscribes to a plan, the subscription created will have the NEW status, which will change as operations related to the subscription are performed. With the subscription status, you can learn how the subscription works, but mainly the current state of the subscription you are dealing with. The table below describes all possible status, their description, and possible next status, depending on the existing condition or action you take.

Subscription status details

Status	Description	Future Status and Triggering Condition
`NEW`	The default status of new subscriptions. If the plan has a trial period, the status change automatically to `TRIAL`.	`TRIAL`: If the plan has a trial period set, it will change automatically from `NEW` to `TRIAL` status.
`NEW`		`INCOMPLETE`: If the subscription does not have a trial period set, the status change automatically to `INCOMPLETE` as it awaits the payment.
`TRIAL`	Indicates the subscription is in the trial period.	`INCOMPLETE`: If the trial period ends and the customer has not payed the first billing cycle.
		`ACTIVE`: If the trial period ends and the customer already payed the first billing cycle invoice.
		`PENDING_CANCELLATION`: In case the subscription was cancelled before the end of the trial period.
		`TERMINATED`: Subscription access is revoked, blocking customer's access.
`INCOMPLETE`	The customer has not payed the subscription first billing cycle.	`ACTIVE`: The customer completes the payment of the first billing cycle invoice.
		`ENDED`: The subscription has completed its final recurring cycle.
		`TERMINATED`: Subscription access is revoked, blocking customer's access.
`ACTIVE`	While the customer pays the subscription correctly, the subscription status stays as `Active`.	`ACTIVE`: The customer completes the payment of the next billing cycle invoice before/at the due date.
		`PAST_DUE`: The current billing cycle expiring date has passed, and the payment hasn't been completed.
		`PAUSED`: The subscription is paused for a period, but not cancelled.
		`ENDED`: The subscription reached its last recurring cycle.
		`PENDING_CANCELLATION`: The subscription was cancelled but it still has not reached the next billing cycle due date.
		`TERMINATED`: Subscription access is revoked, blocking customer's access.
`PAST_DUE`	When a customer with an active subscription fails to make a payment, the subscription status changes to `PAST_DUE`, indicating that the invoice is overdue and requires payment.	`PAST_DUE`: The new billing cycle expiring date has passed, and the payment hasn't been completed.
		`ACTIVE`: The customer completes the payment of the due invoice.
		`ENDED`: The subscription reached its last recurring cycle.
		`PENDING_CANCELLATION`: The subscription was cancelled but it still has not reached the next billing cycle due date.
		`TERMINATED`: Subscription access is revoked, blocking customer's access.
`PAUSED`	Customers have the option to temporarily suspend an active subscription. During this period, no charges will occur unless an action is taken to reactivate it.	`ACTIVE`: The subscription has been resumed.
		`ENDED`: The subscription reached its last recurring cycle.
		`TERMINATED`: Subscription access is revoked, blocking customer's access.
`ENDED`	When a subscription reaches its last recurring cycle, it has come to the end of the plan.	N/A
`PENDING_CANCELLATION`	Whenever a customer cancels their subscription, they will still have access to the benefits of the plan until the next billing cycle due date.	`CANCELLED`: The next billing cycle date has come, the cancelattion will take effect.
`CANCELLED`	When a `PENDING_CANCELLATION` subscription reaches the next billing cycle due date. Thus being actually canceled and revoking the customer's access to the product or service.	N/A
`TERMINATED`	When it is needed to revoke the customer's access from the exact moment of the request, it will use the termination endpoint moving the status here. A subscription can be terminated from every other status except when the cancellation is in process.	N/A

We simplify the subscription workflow into two processes for better understanding. Each one describes part of the subscription workflow. However, use the above table for a complete understanding of the process.

Webhooks

All subscription status change in MoneyHash trigger webhooks. Ensure proper configuration of your webhooks to capture and respond to every subscription event effectively. This ensures real-time updates and smooth management of your subscription lifecycle.

Active subscription cycle

You can offer your customers a trial version when establishing a new subscription. In this case, the subscription will be on TRIAL status and your customer will have access to your service. However, suppose no trial exists, and the invoice remains unpaid. In that case, the subscription will be INCOMPLETE, denying access until payment is completed.

The subscription transitions to the ACTIVE state when the customer pays the first invoice, enabling their access to the service. Customers on trial can seamlessly continue using the service. Customers must pay subsequent invoices before the due date to maintain the subscription active. If the customer does not pay in time, the subscription will transition to PAST_DUE, allowing you to notify the customer and potentially revoke access to your product.

For additional flexibility, MoneyHash provides an option to pause subscriptions. This feature allows you to temporarily suspend billing and revoke access until the customer can reactivate the service.

Concluding a subscription

When it comes to concluding a subscription in MoneyHash, there are three options available.

Ended: Letting the subscription end automatically on its end date.
Cancelled: Cancel the subscription at any point during the billing cycle. The customer will have access to the service until the end billing cycle date is reached.
Terminated: Terminate the subscription instantly, regardless of status. The customer will lose access to the service at the date of termination.

Manage subscriptions

Beyond the initial subscription creation, a suite of operations is available to manage subscriptions efficiently. This includes pausing, resuming, canceling, and terminating each subscription as needed. You also have many ways to update each subscription, such as changing the amount, discount, cycle duration, switching to another plan, and updating the card token to charge automatically.

Pause

API

Temporarily suspend the billing cycle for a subscription, providing flexibility for customers without canceling their commitment.

Resume

API

Reinstate a previously paused subscription, allowing the billing cycle to resume seamlessly.

Cancel

API

Conclude a customer's subscription. Access to subscribed services persists until the conclusion of the ongoing billing cycle.

Terminate

API

Terminate a customer's subscription, resulting in an immediate cessation of billing. The user loses access to subscribed services.

Subscription updates

There are many details in a subscription that can be updated after it has already started. MoneyHash offers ways to manage ongoing subscriptions by updating their data, such as switching between plans, changing the amount to be charged in each cycle, applying discounts, and altering the cycle duration.

To learn more about each update option for your customer's subscription, refer to the Update Subscriptions page.

Simulate subscriptions lifecycle

Testing subscription features and verifying their behavior, especially after a status change, can be time-consuming. MoneyHash provides a solution to expedite subscription testing through pre-configured scenarios in the Sandbox and API.

Simulate Jump to Next Cycle Start Date

Advance the subscription to the next cycle's start date, enabling you to test scenarios without waiting for the actual due date.

Simulate Paying All Issued Invoices

Simulate a situation where a customer is up to date with their payments, paying all invoices issued so far.

Use the Simulate subscription endpoint or MoneyHash's Sandbox for testing. Replace the simulation_subscription parameter with the subscription ID you want to simulate. In your request's body, include the command property with one of the following values:

By leveraging these options, you can assess how your system responds to new status changes triggered by subscription webhooks.

Sandbox

If you require guidance on how to use MoneyHash's Sandbox, refer to the Sandbox guide page. This resource provides detailed instructions to enhance your testing experience.

Subscription invoices

Every subscription billing cycle creates a new invoice your customer needs to pay. Below, you will find the status flow of a new invoice, starting at NEW status:

Subscription invoices status details

Status	Description	Future Status and Triggering Condition
`NEW`	The default status of a new Invoice.	`OPEN`: It goes to open if the due date hasn't passed.
`NEW`	The default status of a new Invoice.	`DUE`: It goes to due if the due date has passed.
`OPEN`	The invoice is open when its due date is still to come and the customer hasn't paid it.	`DUE`: It goes to due if the due date has passed.
		`PAID`: It goes to paid if the customer paid it.
		`CANCELLED`: The invoice gets cancelled.
`DUE`	The invoice is due when its due date has passed and the customer hasn't paid it.	`PAID`: It goes to paid if the customer paid it.
`DUE`		`CANCELLED`: The invoice gets cancelled.
`PAID`	When the invoice has been paid.	N/A
`CANCELLED`	When a invoice is cancelled.	N/A