The subscription plan API allows you to manage the plans that you can subscribe customers to in your business.
Create Subscription Plan
post
This endpoint creates a new subscription plan. You can then create subscribe your customers to these plans and Asyncpay would automatically charge them at the next billing cycle; so you don't need to run any cronjobs or schedulers on your end.
We offer several flexible options for creating recurring charges for your customers. We offer different intervals such as daily, weekly, monthly, quarterly, biannually and annually.
You can also specify a custom trial period if you want customers subscribed in trial mode to have a different duration from the regular billing cycle period. You can set the number of days you want trials to run with the trial_period field.
You can also build on top of our intervals to create truly flexible interval periods with the interval_count field. We calculate your customer's billing cycle by multiplying the interval_count by the interval duration. e.g, if you want your customer's subscription to run every two months, instead of monthly, you can use an interval of monthly, and interval_count of 2. Asyncpay would calculate the billing cycle as 2 * 30, meaning we would charge this customer every 60 days.
The name of the subscription plan. Subscription plan names must be unique within the same business.
intervalstringRequired
How frequently we should charge subscribers to this plan. Supported values are daily, weekly, monthly, quarterly, biannually and annually
amountany ofRequired
The amount we should charge at every billing cycle.
stringOptional
or
numberOptional
currencystring · nullableOptional
The currency of the amount we should charge. If this is not set, we would default to the business' base currency
trial_periodintegerRequired
The number of days you want a trial period of this plan to run. If this value is not set, then a trial subscription would run for the default interval period. e.g a monthly plan in trial mode will run in trial for 30 days.
initial_amountany ofOptional
The amount we should charge the customer the first time. After the first billing cycle, we would charge the value you set for the amount on all subsequent billing cycles. An example usecase for this can be domain name registration; where the first year is cheaper than subsequent years.
stringOptional
or
numberOptional
interval_countstringRequired
This field allows you to create very flexible subscription plans. When this field is set, we multiply this value by the interval period to get the next billing date. For instance, if you want to charge your customers every two months; you can set interval_count to 2, and interval to monthly. When we want to calculate the next billing date, we would multiply the interval_count by the interval period, resulting in 60 days. Meaning we would charge the customer every 60 days. The same rule applies to all the intervals.
meta_dataobjectRequired
An arbitrary object to store additional data for the payment request
Responses
201Success
application/json
post
/v1/subscription-plans
201Success
List Subscription Plans
get
This endpoint provides a paginated list of all the subscription plans that a business has.
Authorizations
AuthenticationstringRequired
Query parameters
pagestringOptional
Defines the page of the subscription plans to fetch
per_pagestringOptional
Defines the number of items to return on each page
Responses
200Success
application/json
get
/v1/subscription-plans
200Success
Fetch Subscription Plan
get
This endpoint fetches a single subscription plan from the subscription plan UUID
Authorizations
AuthenticationstringRequired
Path parameters
SubscriptionUUIDstringRequired
The UUID of the subscription plan you want to fetch
Responses
200Success
application/json
get
/v1/subscription-plans/{SubscriptionUUID}
200Success
Fetch Subscription Plan Subscriptions
get
This endpoint fetches a paginated list of all the subscriptions (or subscribers) that a subscription plan has.
Authorizations
AuthenticationstringRequired
Path parameters
SubscriptionUUIDstringRequired
The UUID of the subscription plan that you want to fetch the subscriptions for
If a plan already has subscriptions attached to it, then updates such as amount, interval, etc, would only take effect on the next billing cycle of the subscribed customer.
N.B. This means that different customers can have the effect of this change at different times, since the change would only take effect when that particular customer's next billing cycle reaches.
Authorizations
AuthenticationstringRequired
Path parameters
SubscriptionUUIDstringRequiredExample: The UUID of the subscription plan you want to update
The name of the subscription plan. Subscription plan names must be unique within the same business.
intervalstring · nullableOptional
How frequently we should charge subscribers to this plan. Supported values are daily, weekly, monthly, quarterly, biannually and annually
amountany ofOptional
The amount we should charge at every billing cycle.
stringOptional
or
numberOptional
currencystring · nullableOptional
The currency of the amount we should charge. If this is not set, we would default to the business' base currency
trial_periodinteger · nullableOptional
The number of days you want a trial period of this plan to run. If this value is not set, then a trial subscription would run for the default interval period. e.g a monthly plan in trial mode will run in trial for 30 days.
initial_amountany ofOptional
The amount we should charge the customer the first time. After the first billing cycle, we would charge the value you set for the amount on all subsequent billing cycles. An example usecase for this can be domain name registration; where the first year is cheaper than subsequent years.
stringOptional
or
numberOptional
interval_countstring · nullableOptional
This field allows you to create very flexible subscription plans. When this field is set, we multiply this value by the interval period to get the next billing date. For instance, if you want to charge your customers every two months; you can set interval_count to 2, and interval to monthly. When we want to calculate the next billing date, we would multiply the interval_count by the interval period, resulting in 60 days. Meaning we would charge the customer every 60 days. The same rule applies to all the intervals.
meta_dataobject · nullableOptional
An arbitrary object to store additional data for the payment request
Responses
201Success
application/json
put
/v1/subscription-plans/{SubscriptionUUID}
201Success
Cancel all subscriptions
post
This endpoint cancels all the subscriptions on a subscription plan.
When a subscription plan is cancelled, it is not immediately terminated. It just means that the subscriptions on this plan will be queued to be terminated when the current billing cycle ends for each subscription on this plan.
Authorizations
AuthenticationstringRequired
Path parameters
SubscriptionUUIDstringRequired
The UUID of the subscription plan whose subscritions you want to cancel
