Create a subscription
Create a subscription and redirect the buyer to checkout.
client object.Creating a subscription returns a checkout URL. You send the buyer there, SUQO runs the whole payment flow, and you learn the outcome from a webhook.
/api/v1/subscriptions/Creates a subscription in pending_checkout state (no billing cycle set yet) and returns a checkout URL for the buyer to pay.
Before you start
You need a pbp_id — a plan billing period's public id. Fetch it from Products; every billing period in billing_periods[] carries one.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
pbp_id | string | Yes | Plan billing period public id (from Products) |
return_url | string (URL) | Yes | Where the buyer returns after checkout |
client | object | Yes | Buyer details — see client object |
When billing is omitted from client, billing info is filled from the buyer's profile. On a reused subscription, only non-null fields overwrite (partial refresh).
Example request
{
"pbp_id": "pbp_3n9k2x",
"return_url": "https://acme.example.com/thank-you",
"client": {
"phone": "9800000001",
"full_name": "John Doe",
"email": "[email protected]",
"address": "Kathmandu, Nepal",
"billing": {
"billing_business_name": "ABC Pvt Ltd.",
"billing_email": "[email protected]",
"billing_address": "Kathmandu, Nepal",
"billing_pan_vat": "111111111"
}
}
}Response
Status: 201 Created
| Field | Type | Description |
|---|---|---|
subscription_id | string (UUID) | — |
pbp_id | string | Echoed |
status | string | Always pending_checkout |
checkout_url | string | <FRONTEND_URL>/pay/<subscription_id> |
next_billing_cycle | datetime | null | null until payment |
created_at | datetime | — |
{
"subscription_id": "sub_9f8a7b6c",
"pbp_id": "pbp_3n9k2x",
"status": "pending_checkout",
"checkout_url": "https://app.suqo.ai/pay/sub_9f8a7b6c",
"next_billing_cycle": null,
"created_at": "2026-07-09T10:15:00Z"
}checkout_url. Send the customer to that
URL — SUQO handles the entire payment flow (collecting details, OTP, wallet/bank payment) and
returns them to your return_url afterward. You don't process the payment yourself.Get the payment result
The return_url only brings the buyer back to your site — it is not proof of payment. Learn the actual outcome from a webhook, which SUQO POSTs to your endpoint for both cases:
| Outcome | Event |
|---|---|
| Payment succeeded — subscription is now active | checkout.succeeded |
| Payment failed — declined or abandoned | checkout.failed |
Don't mark an order paid until you receive checkout.succeeded — a status change alone is not a payment. See Receive webhook events to set the endpoint up, and Webhook events for the payloads.
Both flows report through the same payload: it is keyed by session_id and carries an items array, whether the payment was taken through a checkout session or through this endpoint.
Reuse behaviour
An inactive or expired subscription for the same buyer / product / billing period is reactivated (reset to a clean pending_checkout) rather than duplicated. Only a currently active one triggers the duplicate error.
Errors
The 400s specific to this endpoint are listed under Errors → Creating a subscription.