SUQODocs
User GuideAPI ReferenceSDKs
TypeScript SDK v2.0.0. This version is frozen and no longer updated. Read the latest (2.1.0).

Manage subscriptions

Retrieving, listing, cancelling, renewing and managing subscriptions with the SUQO TypeScript SDK.

Collecting payment? Use checkout sessions — the recommended way, with up to ten items in one checkout. subscriptions.create() below is legacy: still supported, and existing integrations keep working, but new ones should use checkout sessions.

Creating one (legacy)

const response = await suqo.subscriptions.create({
  pbpId: billingPeriod.pbpId, // from products.list() — see Browse the catalog
  returnUrl: "https://your-app.example/return",
  customer: {
    phone: "9800000001",
    fullName: "John Doe",
    email: "[email protected]",
    address: "Kathmandu",
  },
});

response.checkoutUrl; // redirect the buyer here to pay
checkoutUrl is not proof of payment. A newly created subscription comes back in pending_checkout status — redirecting the buyer there starts checkout, it doesn't confirm it succeeded. Learn the real outcome from the checkout.succeeded/checkout.failed webhooks (see Handle webhooks), not from this response.

One live subscription per product

customer.email identifies the buyer. A buyer may hold only one live recurring subscription per product: creating a second one — on any billing period of that same product — throws ValidationError ("You already have a subscription to this product."). See Handle errors.

To restart an inactive subscription, renew it — don't create a new one.

The customer field

Optional nested billing/shipping objects. When billing is omitted, billing details are filled from the buyer's own profile server-side.

interface CustomerInput {
  phone: string;
  fullName: string;
  email: string;
  address: string;
  billing?: { businessName: string; email: string; address: string; panVat?: string };
  shipping?: { phone: string; fullName: string; email: string; address?: string };
}

Listing

const page = await suqo.subscriptions.list();
page.results; // Subscription[]
page.activeSubscriptions; // plus 4 extra counts alongside the usual envelope

Paginated like every list endpoint — see Page through results. SubscriptionPage adds totalSubscriptions/activeSubscriptions/dueSubscriptions/inactiveSubscriptions on top of the common count/next/previous/results shape.

Those four counts cover recurring subscriptions only. One-time purchases appear in results but not in the counts, which is why totalSubscriptions can be lower than count.

Retrieving one

const subscription = await suqo.subscriptions.retrieve("30b0af58-c8bc-4f79-9917-51208b73a0ed");

Returns the same Subscription shape as list()'s results. An empty, "." or ".." id throws SuqoConfigError before any request.

Cancelling

await suqo.subscriptions.cancel(subscriptionId);

This schedules cancellation for the end of the current billing period — it is not immediate. Status moves to pending_cancellation; the subscription stays active until the period actually ends. Cancelling one that's already cancelled or pending cancellation returns it unchanged, so calling it again is safe.

Changing the billing date

await suqo.subscriptions.updateBillingCycle({
  subscriptionId: "30b0af58-c8bc-4f79-9917-51208b73a0ed",
  nextBillingCycle: "2027-06-01", // YYYY-MM-DD, today or a future date
});

This is a collection-level call — the subscription id travels in the request body, not the URL path, mirroring how the API itself models this action.

Resuming

await suqo.subscriptions.resume(subscriptionId);

Undoes a scheduled cancellation and returns the subscription to active; an already-active one is returned unchanged. Once a subscription is cancelled there's nothing to resume — renew it instead.

Renewing

const renewal = await suqo.subscriptions.renew(subscriptionId);
renewal.checkoutUrl; // send the buyer here to pay the next payment

Opens a checkout session for the next payment on one of your own subscriptions, reusing its existing customer and billing period (or partner-priced item) — this is how an inactive subscription is restarted. It returns the same CheckoutSessionResponse as checkoutSessions.create() (publicId, expiresAt, checkoutUrl), and the outcome arrives on the same checkout.* webhooks, keyed by that publicId. Each line item on those deliveries also carries the renewed subscription's subscription_id.

A cancelled or archived subscription, or a paid one-time purchase, can't be renewed — that throws ValidationError.

One-time purchases

A billing period whose intervalType is one_time (see Browse the catalog) is a single purchase, not a cadence. A subscription opened on one has no next billing date, is left out of list()'s counts, and can't be cancelled, resumed, rescheduled or renewed — each of those throws ValidationError. Nothing on the Subscription itself says it's one-time: match its product.pbpId against products.list() to find out.

Status values

Subscription.status is one of the six values in Subscription statuses — that page is the single source for them, shared with the REST API and the webhook events, rather than a second copy maintained here.

isActive on a Subscription is true iff status === "active".

Decimal and nullable fields

Subscription.product.price stays a string end to end — never coerced to number, same as Browse the catalog's pricing fields.

Every field on Subscription.product (productId, name, planName, pbpId, label, price, currency) can be null: the API may send null for any of them. product itself is null when the API sends no product.

Retries

None of the write methods above (create, cancel, updateBillingCycle, resume, renew) are automatically retried on failure — see Handle errors and Idempotency for why, and what changes once the backend supports idempotency keys.

On this page