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

Examples

Runnable example scripts for the SUQO TypeScript SDK.

The SDK ships a set of runnable scripts under examples/ in its repository — real calls against your own sandbox, not mocked. The Quickstart walks through the full end-to-end flow; this page covers the other scripts.

The snippets below are excerpts from those actual scripts, verified against them, not hand-written from memory. If something here ever looks wrong, the real, runnable source under examples/ is the source of truth.

Setup

examples/ isn't part of the published @suqo/sdk package (only the built library is) — to run these scripts as-is, clone the SDK's repository first:

git clone https://github.com/suqo-ai/suqo-sdk-ts
cd suqo-sdk-ts
npm install
npm run build   # examples import @suqo/sdk the same way your own project would

Set SUQO_API_KEY to a sandbox key (su_test_key_...), then run any script with tsx:

SUQO_API_KEY=su_test_key_... npx tsx examples/list-products.ts

Browsing the catalog

const page = await suqo.products.list();
for (const product of page.results) {
  console.log(`${product.name} — ${product.productId}`);
}

Opening a checkout session

From examples/checkout-session.ts. It opens a real session on your account, but nothing is charged until a buyer pays at checkoutUrl, and an unpaid session simply expires:

try {
  const session = await suqo.checkoutSessions.create({
    returnUrl: "https://your-app.example/orders/1234",
    items: [{ pbpId: billingPeriod.pbpId }],
  });
  console.log(`Opened ${session.publicId} — send the buyer to ${session.checkoutUrl}`);

  // Read it back while it's open. Once paid or expired this throws NotFoundError.
  const open = await suqo.checkoutSessions.retrieve(session.publicId);
  for (const item of open.lineItems) {
    console.log(`  ${item.name}: ${item.amount} ${item.currency} (${item.displayLabel})`);
  }
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`Rate limited — try again in ${(err.retryAfter ?? 60_000) / 1000}s.`);
  } else {
    throw err;
  }
}

The subscription lifecycle

Condensed from examples/subscriptions.ts, which wraps each call in its own function and uses the legacy subscriptions.create() flow:

// Cancel — schedules for the end of the current billing period, not immediate
await suqo.subscriptions.cancel(subscriptionId);

// Change the next billing date
await suqo.subscriptions.updateBillingCycle({
  subscriptionId,
  nextBillingCycle: "2027-06-01", // any date from today onward
});

// Resume
await suqo.subscriptions.resume(subscriptionId);

Listing and retrieving customers

const page = await suqo.customers.list();
const first = page.results[0];
if (first) {
  const fetched = await suqo.customers.retrieve(first.id); // id is a string, e.g. "cus_1ce18d624"
  console.log(fetched);
}

Creating and updating customers are covered in Customers — the example script is read-only, so it never writes to your account.

Verifying a webhook, without a real delivery

Signing a payload the same way SUQO's backend does lets you exercise verify() end to end — genuine, tampered, and stale — with no network call at all:

import { createHmac } from "node:crypto";

const secret = "whsec_example_only_do_not_reuse";
const timestamp = String(Math.floor(Date.now() / 1000));
const rawBody = JSON.stringify({
  event: "checkout.succeeded",
  session_id: "cks_3n9k2xQ7m",
  amount: "500.00",
  status: "succeeded",
  line_items: [
    {
      name: "Pro plan",
      amount: "500.00",
      pbp_id: "pbp_3n9k2x",
      currency: "NPR",
      vat_type: null,
      vat_percentage: null,
      discount_amount: null,
      interval_type: "month",
      interval_count: 1,
      image_urls: [],
    },
  ],
});
const signature = `sha256=${createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex")}`;

suqo.webhooks.verify({ rawBody, signature, timestamp, secret }); // → true
Careful with the phone and email you use. subscriptions.ts creates a real subscription, which sends real notifications: an SMS with a live key, and an email in sandbox and live alike. Use a dedicated test number and your own email address — never a real customer's. The checkout-session scripts open a session without a customer, so they send nothing to anyone.

On this page