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

Quickstart

Get your first real call working with the SUQO TypeScript SDK.

1. Install

npm install @suqo/[email protected]

2. Get a sandbox key

Grab a sandbox API key (su_test_key_...) from your seller dashboard. The key's prefix tells the SDK which environment to talk to — there's nothing else to configure.

3. Make your first call

import { SuqoClient } from "@suqo/sdk";

const suqo = new SuqoClient({ apiKey: process.env.SUQO_API_KEY! });

const page = await suqo.products.list();
console.log(page.results);

A full end-to-end flow

A real integration is rarely one isolated call. Here's the shape of a complete flow — pick a product, then open a checkout session for it. This part is a one-off script, the same shape as step 3 above:

import { SuqoClient } from "@suqo/sdk";

const suqo = new SuqoClient({ apiKey: process.env.SUQO_API_KEY! });

// 1. List products, pick a billing period to charge.
const products = await suqo.products.list();
const billingPeriod = products.results[0]?.plan[0]?.billingPeriods[0];

// 2. Open a checkout session. No customerId, so the buyer enters their own details at
//    checkout. checkoutUrl is where the buyer pays, not proof they did.
const session = await suqo.checkoutSessions.create({
  returnUrl: "https://your-app.example/return",
  items: [{ pbpId: billingPeriod!.pbpId }],
});

console.log(`Send the buyer to ${session.checkoutUrl}`);
// Save session.publicId with your order — the webhook below is matched back on it.
checkoutUrl is not proof of payment. You learn the real outcome from a webhook, not from this response — which lives in your server as a persistent route, not this script:
import express from "express";
import { SuqoClient, type WebhookEvent } from "@suqo/sdk";

const app = express();
const suqo = new SuqoClient({ apiKey: process.env.SUQO_API_KEY! });

// Mount express.raw() on this route specifically — see Handle webhooks for why.
app.post("/hooks/suqo", express.raw({ type: "application/json" }), (req, res) => {
  const ok = suqo.webhooks.verify({
    rawBody: req.body,
    signature: req.header("X-SUQO-Signature")!,
    timestamp: req.header("X-SUQO-Timestamp")!,
    secret: process.env.SUQO_WEBHOOK_SECRET!,
  });
  if (!ok) return res.sendStatus(400);

  const event = JSON.parse(req.body.toString()) as WebhookEvent;
  if (event.event === "checkout.succeeded") {
    // event.session_id is the session.publicId you saved — mark that order paid
  }
  res.sendStatus(200); // ack fast; do the real work async
});

Get the signing secret for SUQO_WEBHOOK_SECRET with suqo.webhooks.retrieveSecret(), and register the route with suqo.webhooks.create() — see Handle webhooks. For items, customers and rate limits, see Collect payments.

On this page