List subscriptions
Paginated subscriptions for your account, newest first, 20 per page by default and 100 at most (`page`, `page_size`). The status counters cover recurring subscriptions only — one-time purchases appear in `results` but are excluded from the totals, which is why `total_subscriptions` can be lower than `count`.
Authorization
ApiKey API key issued to the partner, sent with the Bearer prefix — for example: Authorization: Bearer su_key_9f2c4d1ab3….
Keys minted on the live instance are prefixed su_key_ and keys minted on sandbox su_test_key_. The two instances keep separate key tables and separate hosts, so a sandbox key sent to the live host — or the reverse — answers Invalid API key. rather than falling back to the other environment.
In: header
Query Parameters
A page number within the paginated result set.
Number of results to return per page.
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/subscriptions/"{ "count": 90, "next": "https://api.suqo.ai/api/v1/subscriptions?page=2", "previous": null, "total_subscriptions": 85, "active_subscriptions": 60, "due_subscriptions": 10, "inactive_subscriptions": 15, "results": [ { "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "active", "is_active": true, "client": { "phone": "9841000100", "full_name": "Ram Shrestha", "email": "[email protected]", "address": "Kathmandu, Nepal", "billing": { "business_name": "ABC Pvt Ltd.", "email": "[email protected]", "address": "Kathmandu, Nepal", "pan_vat": "9841000100" }, "shipping": { "phone": "9841000100", "full_name": "Ram Shrestha", "email": "[email protected]", "address": "Kathmandu, Nepal" } }, "product": { "product_id": "205293a1-84f4-426e-8f8c-5ddb239e5d2f", "name": "Pro Plan Bundle", "plan_name": "Basic", "pbp_id": "pbp_3n9k2x", "label": "Monthly", "price": "999.00", "currency": "NPR" }, "current_period_start": "2026-07-03T00:00:00Z", "current_period_end": "2026-08-03T00:00:00Z", "next_billing_cycle": "2026-08-03T00:00:00Z", "created_at": "2026-07-03T10:15:00Z" } ]}Renew a subscription POST
Open a checkout session for the next payment on one of your own subscriptions, using its existing customer and billing period (or inline item) rather than resubmitting them. Send the returned `checkout_url` to the buyer to collect payment. A cancelled or archived subscription, or a paid one-time purchase, cannot be renewed.
Create a subscription POST
Create a subscription for a client against one of your billing periods. `client.phone` identifies the buyer and must be a Nepali mobile number (10 digits starting with 96, 97 or 98); a +977 country code is accepted and stripped. The subscription starts in `pending_checkout`; send the returned `checkout_url` to the client to collect payment. `client.email` and `client.phone` are read back on the subscription as `client.email` and `client.phone`, but the `client.billing` block loses its `billing_` prefix on the way back out. `return_url` is required despite reading as optional on the model behind this body — a missing, null or blank value is rejected the same way. A client may hold only one live recurring subscription per product, so a second one on a different billing period of the same product is refused. This endpoint takes no idempotency key: a retried request that timed out opens a second subscription and a second checkout, so reconcile by `subscription_id` before retrying.