Subscription Payments

This option is used only for integration partners using the subscription model

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 subscription 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 however, just 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 remained 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.


Did this page help you?