search

Subscriptions

The subscriptions API allows you to manage your customer's subscriptions as well as subscribe them to plans.

hashtag
Subscribe to Subscription Plan

post

This endpoint is similar to the initiate payment request, but it is used exclusively to subscribe a customer to a plan.

This endpoint initiates a payment request and a checkout process with the sole intention of subscribing the customer to a specified plan.

A customer can either be subscribed to a plan in trial mode (which charges the lowest possible charge a payment channel accepts to save a payment method) or in the default mode that charges the customer the regular subscription fee defined in the subscription plan.

Authorizations
AuthenticationstringRequired
Body
customer_uuidstring · nullableOptional

The UUID of the customer that is initiating this payment request. This field is required if customer_email and customerfields are absent.

customer_emailstring · nullableOptional

The email of the customer that is intiating this payment request. This field is required if customer_email and customerfields are absent.

referencestring · nullableOptional

Your unique reference of this payment request.

payment_channelstring · nullableOptional

The slug of the payment channel that Asyncpay should route this payment through.

success_redirect_urlstring · nullableOptional

A URL to redirect the customer to after a successful payment

failure_redirect_urlstring · nullableOptional

A URL to redirect the customer to after a cancelled payment

subscription_plan_uuidstringRequired

The UUID of the subscription plan.

save_payment_methodboolean · nullableOptional

A boolean flag that tells Asyncpay whether or not to save the payment method the user uses to make this payment.

is_trialboolean · nullableOptional

A booelan flag that tells Asyncpay that you are subscribing the user to a plan in trial mode. In this mode, Asyncpay would charge the lowest possible fee that the payment channel supports for the first billing cycle, after which it would charge the regular subscription fee.

meta_dataobject · nullableOptional

An arbitrary object to store additional data for the payment request

Responses
post
/v1/payment-requests/subscribe-to-plan
201Success
circle-exclamation

Use this endpoint to subscribe a customer without an initial charge—ideal for true free trials. Since payment channels like Paystack and Flutterwave require a charge to save a card, you can prompt the customer to save a payment method later. Asyncpay will attempt to charge it at the end of the first cycle or cancel if unpaid.

Alternatively, use the subscribe-to-plan endpoint with the is-trial field to charge the card with the minimum amount required by the payment channel to save the payment method upfront.

hashtag
Subscribe Customer To Plan (Without initial charge)

post

This endpoint subscribes a customer to a plan without charging them for the first billing cycle.

Only use this endpoint if you are sure you don't want the customer to pay anything and you also don't want them to add a payment instrument for the first billing cycle.

If you want to do a trial subscription and you want them to add their payment method for subsequent charges, please use the /v1/payment-requests/subscribe-to-plan endpoint instead.

Authorizations
AuthenticationstringRequired
Body
customer_uuidstring · nullableOptional

The UUID of the customer that is initiating this payment request. This field is required if customer_email is absent.

customer_emailstring · nullableOptional

The email of the customer that is intiating this payment request. This field is required if customer_uuid is absent.

subscription_plan_uuidstringRequired

The UUID of a subscription plan.

is_trialboolean · nullableOptional

A booelan flag that tells Asyncpay that you are subscribing the user to a plan in trial mode. In this mode, Asyncpay would charge the lowest possible fee that the payment channel supports for the first billing cycle, after which it would charge the regular subscription fee.

Responses
post
/v1/subscriptions/subscribe
201Success

hashtag
Fetch Subscription

get

This endpoint fetches all the details for a single subscription using its UUID.

Authorizations
AuthenticationstringRequired
Path parameters
SubscriptionUUIDstringRequired

The UUID of the subscription whose information you want to fetch.

Responses
chevron-right
200Success
application/json
get
/v1/subscriptions/{SubscriptionUUID}
200Success

hashtag
Generate Subscription Link

post

This endpoint is used to generate a subscription link.

A subscription link allows you to subscribe a user without building a frontend yourself, it leverages our subscription UI to automatically handle the initial checkout process and subscribe the user to the specified subscription plan.

Authorizations
AuthenticationstringRequired
Body
customer_uuidstringRequired

The UUID of the customer we want to subscribe to a plan

subscription_plan_uuidstringRequired

The UUID of the subscription plan.

is_trialboolean · nullableOptional

A booelan flag that tells Asyncpay that you are subscribing the user to a plan in trial mode. In this mode, Asyncpay would charge the lowest possible fee that the payment channel supports for the first billing cycle, after which it would charge the regular subscription fee.

success_redirect_urlstring · nullableOptional

A URL to redirect the customer to after a successful subscription

failure_redirect_urlstring · nullableOptional

A URL to redirect the customer to after a failed subscription attempt

payment_channelstringRequired

The slug of the payment channel that Asyncpay should route this payment through.

Responses
post
/v1/subscriptions/generate-link
201Success

hashtag
Check Subscription Status

post

This endpoint checks the status of a customer's subscription. It uses the customer UUID and subscription plan UUID to check if the customer is subscribed to the specified plan and the status of the customer's subscription.

Authorizations
AuthenticationstringRequired
Body
subscription_plan_uuidstringRequired
customer_uuidstringRequired
Responses
chevron-right
200Success
application/json
post
/v1/subscriptions/check-status

hashtag
Cancel Subscription

post

This endpoint cancels a customer's subscription.

A cancelled subscription is not immediately terminated; this just means that the subscription would no longer be charged at the next billing cycle, and it will be terminated at that point.

You can re-enable a cancelled subscription with the /v1/subscriptions/re-enable endpoint.

If you want to immediately terminate an active subscription, please use the /v1/subscriptions/terminate endpoint.

Authorizations
AuthenticationstringRequired
Body
subscription_plan_uuidstringRequired
customer_uuidstringRequired
Responses
post
/v1/subscriptions/cancel

hashtag
Re-enable subscription

post

This endpoint is used to enable a subscription that was previously cancelled.

When this is done, Asyncpay would charge the customer at the next billing cycle.

Authorizations
AuthenticationstringRequired
Body
subscription_plan_uuidstringRequired

The UUID of the subscription plan you want to enable the customer's subscription for

customer_uuidstringRequired

The UUID of the customer

Responses
post
/v1/subscriptions/re-enable
201Success

hashtag
Terminate Subscription

post

This endpoint is used to immediately end a customer's subscription to a plan. Unlike the /v1/subscriptions/cancel that ends the subscription at the next billing cycle, this endpoint ends the subscription immediately; which means the customer is no longer receiving value for this subscription.

You should be careful when using this endpoint because it is not reversible. Because of this, we put a flag in place called force_terminate. By default, when you try to terminate a subscription, Asyncpay would flag the request and return an error if the subscription you're trying to terminate has payments attached to it. This means subscriptions created with the /v1/subscriptions/subscribe will work just fine since no payment/charge was initiated to create the subscription, however for other subscriptions that have any payments attached to them, you have to provide the force_terminate field and set it to true for Asyncpay to terminate the subscription.

Authorizations
AuthenticationstringRequired
Body
subscription_plan_uuidstringRequired

The UUID of the subscription plan you want to terminate the customer from

customer_uuidstringRequired

The UUID of the customer

cancellation_reasonstring · nullableOptional

An optional field describing the reason for this termination

force_terminateboolean · nullableOptional

A flag to force Asyncpay to terminate the subscription if it has any payments attached to it

Responses
post
/v1/subscriptions/terminate
PreviousSubscription PlansNextBeneficiaries

Last updated