Subscription Payments

Ezypay offers a wide range of options to build your subscription setup. Once plans have been created, you can sign up a customer onto a specific plan and the subscription payments can then be tailored to the customer.

You can use plans with their existing default values or specify your own for added customisation such as when the billing starts, ends and whether a prorate is calculated. A subscription lists all the future invoices that the customer will need to pay. Subscriptions will run automatically allowing ease and efficiency when billing customers.

Create a Subscription

To create a subscription (API), you need to have a customer and a plan. A subscription inherits all billing details from the Plan but these details can still be overridden on the subscription level such as: start date, recurring billing details, first billing rules, and setup payment details. Subscriptions can be created with the following options:

Type	Definition
Pending	Subscriptions with the `status = pending` will not have active billing runs. Once you are satisfied with the subscription, you can activate it to start billing. For example, you can subscribe a customer to a gym plan but the subscription only becomes active after the customer has attended their first onboarding session. To create a pending subscription, set `markAsPending` to `true`. A subscription without a payment method token. These are pending subscriptions can be activated later once you are ready to add payment method token information.
Ongoing	Create subscriptions with no set automatic ending that will continue billing until it is manually cancelled. To create an ongoing subscription, ensure `billingEnd = ongoing`, `billingEndValue = null`.
Starting on specific day	Create subscriptions that start billing on a specific day: To create this subscription, set `billingStart` and `billingStartValue`. Billing cycle can start on a preferred day such as every Wednesday. * Billing cycle can start on a preferred day in the month such as every 15th.
Ending when specific amount is collected	Create subscriptions that continue billing until a specific amount is collected, prorating the last billing as necessary. To create this subscription, set `billingEnd` and `billingEndValue`. For example set `billingEnd` = amount_collected, `billingEndValue` = 1299.99. You can check if a subscription is setup this way if `endTargetAmount` has a value but `endTargetBillingCycle` is null.
Ending after specific number of billing cycles	Create subscriptions that continue billing for a specific number of billing cycles. To create this subscription, set `billingEnd` and `billingEndValue`. For example set `billingEnd = billing_cycles`, `billingEndValue = 10`. You can check if a subscription is setup this way if `endTargetAmount` is null and `endTargetBillingCycles` has a value.
Ending on a specific date	Create subscriptions that end on a fixed date. To create this subscription, set `billingEnd` and `billingEndValue`. For example, set `billingEnd = end_date`, `billingEndValue = 2020-10-25`. When creating a plan, you can leave `billingEndValue` as null but for an active subscription, `billingEndValue` must be given a value or else it will have no end date.
One-off single payment	Billing the customer as a one-off payment without ongoing subscription.

Subscription Status

The status of a subscription can inform you on the state of the subscription and the invoices generated from it, as shown below:

Status	Definition
Pending	The subscription has not yet been activated and has no start date set. No billing cycles will run for this subscription.
Future	The subscription has not yet started because the start date is on a future date.
Active	The subscription is actively being billed.
Past Due	The subscription has at least one invoice with a status that is `past_due`. Subscriptions will remain at this status until all `past_due` invoices have been settled (i.e. either paid or written off). Subscriptions with payment retry scheduled will still appear as `past_due`.
Completed	The subscription has ended and the final invoice has being generated. The subscription is considered ended when the subscription has reached its end date or has fulfilled its end billing requirements as defined in the variable `billingEnd`. The end date refers to the termination of billing for the customer and not necessarily the customer's contract or membership with the merchant.
Cancelled	The subscription was cancelled by the merchant before completing its course. No billing cycles will run for this subscription and any outstanding payments must be resolved by the merchant separately.

Preview a Subscription

Before creating a subscription, you can ^preview a subscription (API) first to double-check that details inherited from the plan object are correct. Subscription previews do not create subscriptions.

📘
Previewing a subscription is not the same as creating a pending subscription. Pending subscriptions are subscriptions that have been created with status pending and do not have active billing cycles. Pending subscriptions can be activated at a later date.
Previewing a subscription provides a preliminary preview of the subscription details which are mostly inherited from its plan object. You cannot activate a preview subscription.

Change an Existing Subscription

After creating a subscription, you can change an existing subscription as follows:

Activate a pending subscription (API). You will need to provide payment details and start date to activate the subscription and start billing
Change an existing subscription's payment method token (API). This allows you to change a customer's payment method in case it becomes invalid

If a plan is updated, the existing customer subscriptions will not be affected as they remain grandfathered to the previous plan's terms that were agreed on during signup. Plan updates will only be effective for customers that subscribe to the plan after the update occurs.

📘
If you want to change the details of a specific subscription invoice, such as amount or billing date, see ^Update a future invoice.

Pausing a Subscription

An on-going subscription can be paused without having to cancel the subscription. For example, a customer wants to pause or freeze their subscription because they are going on holiday but wish to continue their subscription as usual once they return from their vacation. In this scenario, you can ^delete a future invoice for the period you want to skip. Deleting a future invoice will skip an invoice for only that billing cycle but the subscription itself will remain unchanged and continue as usual. An additional billing cycle is added to the subscription to replace the deleted invoice.

Cancel a Subscription

Cancellation stops subsequent billing and payment collections but outstanding payments will remain and need to be resolved separately. The status of the subscription will change to cancelled but the invoices will remain unchanged. For example, any invoices with status past_due will remain past_due. You cannot reverse a cancelled subscription.