Subscriptions
The subscriptions API allows you to manage your customer's subscriptions as well as subscribe them to plans.
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.
The UUID of the customer that is initiating this payment request. This field is required if customer_email and customerfields are absent.
The email of the customer that is intiating this payment request. This field is required if customer_email and customerfields are absent.
Your unique reference of this payment request.
The slug of the payment channel that Asyncpay should route this payment through.
A URL to redirect the customer to after a successful payment
A URL to redirect the customer to after a cancelled payment
The UUID of the subscription plan.
A boolean flag that tells Asyncpay whether or not to save the payment method the user uses to make this payment.
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.
An arbitrary object to store additional data for the payment request
POST /v1/payment-requests/subscribe-to-plan HTTP/1.1
Host:
Authentication: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 149
{
"customer_uuid": "953fb557-2da9-11f0-ac87-92433b0171f7",
"subscription_plan_uuid": "82b02e0b-34aa-11f0-ac87-92433b0171f7",
"payment_channel": "paystack"
}{
"message": "Payment request initiated successfully",
"status": "success",
"data": {
"payment_request": {
"uuid": "eric-02a965e2-3790-11f0-ac87-92433b0171f7",
"ref": "AsP-6f73551721017",
"intent": "subscription",
"env_mode": "live",
"payment_method": "Unknown",
"currency": "NGN",
"amount": "200",
"amount_to_usd": "0.12",
"description": "Subscription to One Piece",
"meta_data": null,
"discount": null,
"cancel_redirect_url": null,
"status": "open",
"created_at": "2025-05-23T04:40:10.000000Z",
"updated_at": "2025-05-23T04:40:11.000000Z",
"deleted_at": null,
"last_transaction": {
"uuid": "b4b66f90-6822-4275-a275-ec0f273c5fe5",
"ref": "AsT-c17c73f3f63f2",
"mode": "redirect",
"env_mode": "live",
"payment_channel_slug": "paystack",
"payment_method": "Unknown",
"currency": "NGN",
"amount": "200",
"amount_to_usd": "0.12",
"description": "Subscription to One Piece",
"status": "pending",
"created_at": "2025-05-23T04:40:11.000000Z",
"updated_at": "2025-05-23T04:40:11.000000Z",
"deleted_at": null,
"business_payment_channel": {
"is_enabled": 1,
"payment_channel_slug": "paystack",
"is_default": 1,
"created_at": "2024-12-11T04:27:43.000000Z",
"updated_at": "2024-12-11T04:27:43.000000Z",
"webhook_url": "https://api.asyncpay.io/v1/system/hooks/i_FPCY-c/paystack",
"payment_channel": {
"slug": "paystack",
"display_name": "Paystack",
"summary": "Paystack helps new generation of innovative, forward-looking businesses in Africa get paid by anyone, anywhere in the world.",
"logo": "https://api.asyncpay.io/payment_channels/Paystack.svg",
"logo_full": "https://api.asyncpay.io/payment_channels/Paystack-Full.svg",
"theme_color": "#66B5FF"
},
"business": {
"business_id": "faa21200-1f36-45b3-b5e8-6adaccf5d7d6",
"name": "Live Paystack",
"env_mode": "live",
"business_category": null,
"base_currency": "NGN",
"logo": null,
"webhook_url": "https://webhook.site/73731d7f-b92c-423c-8393-89ebe77e02c0",
"default_redirect_url": null,
"enabled_webhooks": 1,
"send_subscription_mails": 1,
"deleted_at": null,
"created_at": "2024-12-11T04:21:38.000000Z",
"updated_at": "2024-12-16T10:03:17.000000Z"
}
}
},
"payment_channel": {
"slug": "paystack",
"display_name": "Paystack",
"summary": "Paystack helps new generation of innovative, forward-looking businesses in Africa get paid by anyone, anywhere in the world.",
"logo": "https://api.asyncpay.io/payment_channels/Paystack.svg",
"logo_full": "https://api.asyncpay.io/payment_channels/Paystack-Full.svg",
"theme_color": "#66B5FF"
},
"customer": {
"customer_id": "LIV-531018855",
"uuid": "953fb557-2da9-11f0-ac87-92433b0171f7",
"env_mode": "live",
"first_name": "Roronoa",
"last_name": "Zoro",
"name": null,
"external_customer_ids": null,
"email": "[email protected]",
"phone_code": "+234",
"phone_number": "8246578707",
"address_line_1": "The Going Merry",
"address_line_2": "The Thousand Sunny",
"city": "Lagos",
"state": "Lagos",
"zip": "101233",
"country": "Nigeria",
"meta_data": {
"uid": "84734",
"status": "Dignified"
},
"deleted_at": null,
"created_at": "2025-05-10T14:18:02.000000Z",
"updated_at": "2025-05-10T14:18:02.000000Z",
"full_name": "Roronoa Zoro"
},
"business": {
"business_id": "faa21200-1f36-45b3-b5e8-6adaccf5d7d6",
"name": "Live Paystack",
"env_mode": "live",
"business_category": null,
"base_currency": "NGN",
"logo": null,
"webhook_url": "https://webhook.site/73731d7f-b92c-423c-8393-89ebe77e02c0",
"default_redirect_url": null,
"enabled_webhooks": 1,
"send_subscription_mails": 1,
"deleted_at": null,
"created_at": "2024-12-11T04:21:38.000000Z",
"updated_at": "2024-12-16T10:03:17.000000Z"
},
"subscription_plan": {
"uuid": "82b02e0b-34aa-11f0-ac87-92433b0171f7",
"env_mode": "live",
"name": "One Piece",
"tags": null,
"send_subscription_mails": 1,
"initial_amount": null,
"initial_amount_to_usd": "0.00",
"trial_period": null,
"amount": "200",
"amount_to_usd": "0.12",
"currency": "NGN",
"interval": "monthly",
"interval_count": null,
"link_id": "fv6CGsz6",
"meta_data": null,
"status": "inactive",
"deleted_at": null,
"created_at": "2025-05-19T12:12:19.000000Z",
"updated_at": "2025-05-23T00:21:10.000000Z",
"total_subscribers": 0,
"total_subscription_payments": 0,
"number_of_subscription_payments": 0
}
},
"action": "https://checkout.paystack.com/kdr8txyil7tti4f"
}
}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.
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.
The UUID of the customer that is initiating this payment request. This field is required if customer_email is absent.
The email of the customer that is intiating this payment request. This field is required if customer_uuid is absent.
The UUID of a subscription plan.
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.
POST /v1/subscriptions/subscribe HTTP/1.1
Host:
Authentication: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 108
{
"customer_email": "[email protected]",
"subscription_plan_uuid": "bc36f6c1-a77a-11ee-94a9-0242ac120006"
}{
"message": "Customer subscribed to plan successfully",
"status": "success",
"data": {
"uuid": "4d06e330-3789-11f0-ac87-92433b0171f7",
"env_mode": "test",
"status": "active",
"cancelled_at": null,
"cancellation_completed": 0,
"cancellation_reason": null,
"next_payment_at": "2025-05-24",
"last_successful_payment_at": null,
"deleted_at": null,
"created_at": "2025-05-23T03:52:09.000000Z",
"updated_at": "2025-05-23T03:52:09.000000Z",
"last_termination_id": null,
"payments_count": 0,
"subscription_plan": {
"uuid": "2e09c3a3-b779-11ef-8d1a-621bbad79fdf",
"env_mode": "live",
"name": "Paystack Daily Savings",
"tags": null,
"send_subscription_mails": 1,
"initial_amount": null,
"initial_amount_to_usd": "0.00",
"trial_period": null,
"amount": "300",
"amount_to_usd": "0.35",
"currency": "NGN",
"interval": "daily",
"interval_count": 1,
"link_id": "19kCgHKm",
"meta_data": null,
"status": "active",
"deleted_at": null,
"created_at": "2024-12-11T04:34:16.000000Z",
"updated_at": "2025-05-23T00:25:55.000000Z",
"total_subscribers": 3,
"total_subscription_payments": 27000,
"number_of_subscription_payments": 54
},
"customer": {
"customer_id": "LIV-d7a69f411",
"uuid": "a588dcc2-2db4-11f0-ac87-92433b0171f7",
"env_mode": "live",
"first_name": null,
"last_name": null,
"name": "Monkey D. Luffy",
"external_customer_ids": null,
"email": "[email protected]",
"phone_code": "+234",
"phone_number": "8242598707",
"address_line_1": "The Going Merry",
"address_line_2": "The Thousand Sunny",
"city": "Lagos",
"state": "Lagos",
"zip": "101233",
"country": "Nigeria",
"meta_data": null,
"deleted_at": null,
"created_at": "2025-05-10T15:37:14.000000Z",
"updated_at": "2025-05-10T15:37:14.000000Z",
"full_name": "Monkey D. Luffy"
}
}
}This endpoint fetches all the details for a single subscription using its UUID.
The UUID of the subscription whose information you want to fetch.
GET /v1/subscriptions/{SubscriptionUUID} HTTP/1.1
Host:
Authentication: YOUR_API_KEY
Accept: */*
{
"message": "Subscriber fetched successfully",
"status": "success",
"data": {
"subscriber": {
"uuid": "cd1692af-3865-11f0-ac87-92433b0171f7",
"env_mode": "live",
"status": "active",
"cancelled_at": null,
"cancellation_completed": 0,
"cancellation_reason": null,
"next_payment_at": "2025-06-23",
"last_successful_payment_at": "2025-05-24 06:10:33",
"deleted_at": null,
"created_at": "2025-05-24T06:10:33.000000Z",
"updated_at": "2025-05-24T06:10:33.000000Z",
"payments_count": 1,
"customer": {
"customer_id": "LIV-531018855",
"uuid": "953fb557-2da9-11f0-ac87-92433b0171f7",
"env_mode": "live",
"first_name": "Roronoa",
"last_name": "Zoro",
"name": null,
"external_customer_ids": {
"paystack": 276177914
},
"email": "[email protected]",
"phone_code": "+234",
"phone_number": "8246578707",
"address_line_1": "The Going Merry",
"address_line_2": "The Thousand Sunny",
"city": "Lagos",
"state": "Lagos",
"zip": "101233",
"country": "Nigeria",
"meta_data": {
"uid": "84734",
"status": "Dignified"
},
"deleted_at": null,
"created_at": "2025-05-10T14:18:02.000000Z",
"updated_at": "2025-05-23T06:11:15.000000Z",
"full_name": "Roronoa Zoro"
},
"subscription_plan": {
"uuid": "82b02e0b-34aa-11f0-ac87-92433b0171f7",
"env_mode": "live",
"name": "One Piece",
"tags": null,
"send_subscription_mails": 1,
"initial_amount": null,
"initial_amount_to_usd": "0.00",
"trial_period": null,
"amount": "200",
"amount_to_usd": "0.12",
"currency": "NGN",
"interval": "monthly",
"interval_count": null,
"link_id": "fv6CGsz6",
"meta_data": null,
"status": "inactive",
"deleted_at": null,
"created_at": "2025-05-19T12:12:19.000000Z",
"updated_at": "2025-05-23T00:21:10.000000Z",
"total_subscribers": 2,
"total_subscription_payments": 400,
"number_of_subscription_payments": 2
},
"subscription_payments": [
{
"uuid": "cd1736f8-3865-11f0-ac87-92433b0171f7",
"env_mode": "live",
"amount_charged": "200",
"amount_charged_to_usd": null,
"was_successful": true,
"failure_message": null,
"currency": "NGN",
"created_at": "2025-05-24T06:10:33.000000Z",
"updated_at": "2025-05-24T06:10:33.000000Z",
"deleted_at": null
}
]
}
}
}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.
The UUID of the customer we want to subscribe to a plan
The UUID of the subscription plan.
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.
A URL to redirect the customer to after a successful subscription
A URL to redirect the customer to after a failed subscription attempt
The slug of the payment channel that Asyncpay should route this payment through.
POST /v1/subscriptions/generate-link HTTP/1.1
Host:
Authentication: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 120
{
"subscription_plan_uuid": "953fb557-2da9-11f0-ac87-92433b0171f7",
"customer_uuid": "82b02e0b-34aa-11f0-ac87-92433b0171f7"
}{
"message": "Customer subscription linked generated successfully",
"status": "success",
"data": {
"link": "https://subscribe.asyncpay.io/?subscription_claim=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJBc3luY3BheSIsImF1ZCI6Imh0dHBzOi8vYXBpLmFzeW5jcGF5LmlvIiwiaWF0IjoxNzQ3OTcyODY2LCJleHAiOjE3NDc5NzY0NjYsImxpbmtfaWQiOiJmdjZDR3N6NiIsImN1c3RvbWVyX2lkIjoiTElWLTUzMTAxODg1NSJ9.DIpRibU8LSWarKBmDxjUV38okGVSy48IqLNhraHmq80&public_key=async_pk_480a86db0691e5b2393702b666929df2492caae2c115b4fb395858c64774"
}
}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.
POST /v1/subscriptions/check-status HTTP/1.1
Host:
Authentication: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 120
{
"subscription_plan_uuid": "82b02e0b-34aa-11f0-ac87-92433b0171f7",
"customer_uuid": "953fb557-2da9-11f0-ac87-92433b0171f7"
}{
"message": "No subscription found",
"status": "success",
"data": {
"subscription": null,
"subscription_status": "customer_not_subscribed_to_plan"
}
}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.
POST /v1/subscriptions/cancel HTTP/1.1
Host:
Authentication: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 120
{
"subscription_plan_uuid": "82b02e0b-34aa-11f0-ac87-92433b0171f7",
"customer_uuid": "953fb557-2da9-11f0-ac87-92433b0171f7"
}{
"message": "Subscription cancelled successfully",
"status": "success"
}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.
The UUID of the subscription plan you want to enable the customer's subscription for
The UUID of the customer
POST /v1/subscriptions/re-enable HTTP/1.1
Host:
Authentication: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 120
{
"subscription_plan_uuid": "82b02e0b-34aa-11f0-ac87-92433b0171f7",
"customer_uuid": "953fb557-2da9-11f0-ac87-92433b0171f7"
}{
"message": "Subscription re-enabled successfully",
"status": "success",
"data": {
"subscription": {
"uuid": "0584dba4-3857-11f0-ac87-92433b0171f7",
"env_mode": "live",
"status": "active",
"cancelled_at": null,
"cancellation_completed": 0,
"cancellation_reason": null,
"next_payment_at": "2025-06-23",
"last_successful_payment_at": "2025-05-24 04:24:45",
"deleted_at": null,
"created_at": "2025-05-24T04:24:45.000000Z",
"updated_at": "2025-05-24T05:45:58.000000Z",
"payments_count": 1
}
}
}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.
The UUID of the subscription plan you want to terminate the customer from
The UUID of the customer
An optional field describing the reason for this termination
A flag to force Asyncpay to terminate the subscription if it has any payments attached to it
POST /v1/subscriptions/terminate HTTP/1.1
Host:
Authentication: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 120
{
"subscription_plan_uuid": "82b02e0b-34aa-11f0-ac87-92433b0171f7",
"customer_uuid": "953fb557-2da9-11f0-ac87-92433b0171f7"
}{
"message": "Subscription terminated successfully",
"status": "success"
}Last updated