SUQO API Integration Guide

This guide walks through integrating the SUQO API into your product — from getting your API key to creating subscribers, triggering renewals, and handling subscription state programmatically. If you've been managing recurring billing with spreadsheets or custom eSewa callbacks, this is the integration that replaces all of it. Also see the For Developers page for an overview of integration options.

The SUQO API is a REST API. All endpoints are under /api/v1/external/. Authentication uses a Bearer token. Requests and responses are JSON.

---

Before you start

You'll need a SUQO account with KYC completed. KYC connects your business to Nepal's payment infrastructure — it's required before you can collect payments. Sign up at app.suqo.ai, complete verification, and your API key will be available in your dashboard under Settings → API.

You'll also need at least one subscription plan created. Plans define the billing cycle, price, and payment methods. You can create plans via the dashboard or via the API — for most integrations, creating plans in the dashboard once and referencing them by ID in your code is the simplest approach.

---

Authentication

Every API request requires an Authorization header with your Bearer token:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Keep your API key server-side. Never expose it in client-side code or a public repository.

---

Step 1: Create a subscriber

When a customer signs up for a subscription in your product, create them as a subscriber in SUQO. This starts their billing cycle and, depending on the mode you choose, either sends them a payment link or just schedules renewal reminders.

POST /api/v1/external/subscriptions/

{
  "plan": "plan_abc123",
  "subscriber_name": "Aarav Shrestha",
  "subscriber_phone": "9800000000",
  "subscriber_email": "[email protected]",
  "mode": "reminder_and_payment",
  "start_date": "2026-06-01"
}

The mode field controls how SUQO manages the renewal cycle:

• reminder_and_payment — SUQO sends SMS reminders with a payment link at renewal. Subscribers pay via eSewa, Khalti, or ConnectIPS. Payment is recorded automatically.
• reminder_only — SUQO sends SMS reminders but does not generate a payment link. Use this if you handle payment collection separately and only want SUQO to manage the reminder cycle.

A successful response returns the subscriber object:

{
  "id": "sub_x9k2m",
  "status": "active",
  "plan": "plan_abc123",
  "subscriber_name": "Aarav Shrestha",
  "subscriber_phone": "9800000000",
  "start_date": "2026-06-01",
  "next_renewal_date": "2026-07-01",
  "payment_link": "https://app.suqo.ai/pay/sub_x9k2m"
}

Store the id in your database — you'll use it to query status, trigger renewals, and cancel subscriptions.

---

Step 2: Check subscription status

At any point, you can query a subscriber's current status — useful for access control decisions in your product (should this subscriber have access right now?).

GET /api/v1/external/subscriptions/{id}/

The response includes the subscriber's current status:

• active — paid and within the current billing period
• due — renewal date has arrived, payment not yet received
• grace — past renewal date, within a configured grace period
• overdue — past grace period, payment not received
• cancelled — subscription has been cancelled

Use this status to gate features or access in your product. A subscriber with active or grace status has a current subscription; overdue or cancelled means access should be restricted.

---

Step 3: Trigger a manual renewal

SUQO handles renewal reminders automatically based on the billing cycle. But if you need to trigger a renewal manually — for example, when a subscriber pays through a different channel and you want to record it and reset their billing cycle — use the renew endpoint:

POST /api/v1/external/subscriptions/{id}/renew/

{
  "payment_method": "cash",
  "note": "Paid at front desk"
}

This marks the subscription as renewed, updates next_renewal_date, and moves status back to active.

---

Step 4: Cancel a subscription

When a subscriber cancels or you need to terminate a subscription:

POST /api/v1/external/subscriptions/{id}/cancel/

{
  "reason": "Subscriber requested cancellation"
}

The subscription status moves to cancelled. No further renewal reminders will be sent.

---

A complete integration flow

Here's how a typical product integration looks end to end:

---

Things to know

No per-call charges. API access is free. There are no rate limits that would affect normal usage, and no developer tier required. You pay only for SMS credits when reminders are sent.

No merchant API required. You do not need your own eSewa or Khalti merchant account. SUQO handles the payment gateway integration. Subscribers pay through SUQO's payment layer; funds settle to your registered account.

Auto-debit readiness. When auto-debit becomes available in Nepal, it will be exposed through the same API endpoints. Products already integrated with SUQO will get auto-debit support without changing their integration structure.

Webhooks. Webhook support is on the roadmap. Until then, poll subscription status via the GET endpoint when you need to check payment state.

The full API reference is at suqo.ai/docs/api.