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

Changelog & versioning

Release history and versioning policy for the SUQO TypeScript SDK.

Versioning policy

The SDK follows strict SemVer: MAJOR.MINOR.PATCH.

  • MAJOR — bumped on either trigger: the API's wire contract breaks — whether with a new path version (/api/v1/ → /api/v2/) or inside the existing one — or the SDK introduces its own breaking change with no API change at all (a renamed export, a changed return shape). So an SDK major no longer equals the API path version: 2.0.0 still talks to /api/v1/.
  • MINOR — additive, backward-compatible: a new resource, a new optional parameter, a new non-breaking field.
  • PATCH — fixes only, no contract change of any kind.

Anything removed is deprecated one minor ahead with a documented warning, removed only at the next major — no feature is ever removed in a minor or patch release.

Compatibility table

SDK VersionSupported API VersionChange TypeStatus
2.0.0v1API wire-breaking change within /api/v1/ (checkout webhook payload, customer create body); checkout sessions, renew, webhook managementShipped
1.1.0v1Added customers.create/update; SDK-only type fixes shipped as a minor (see below)Shipped
1.0.0v1Initial releaseShipped

2.0.0 - 2026-11-18

Why a major: the API changed its wire contract within /api/v1/ — the checkout webhook payload and the customer create body — which always forces a new SDK major. This release also brings the SDK up to the API's full surface: checkout sessions, subscription retrieve/renew and webhook management. Each breaking change below says what to change when upgrading.

Changed

  • Breaking: CheckoutSucceededEvent / CheckoutFailedEvent match the API's new payload: one delivery per checkout session, { event, session_id, amount, status, line_items }, with no top-level subscription_id. Each line item carries name, amount, pbp_id, currency, VAT and discount fields and its interval; a renewal's line items also carry subscription_id. Payments taken through subscriptions.create() report the same way. Upgrading: match deliveries on session_id (the publicId a session was opened with), not subscription_id. See Handle webhooks.
  • Breaking: expires_at on the api_key.* webhook events is string | null — a key created without an expiry sends null. Upgrading: handle null where you read it as a date.
  • Breaking: customers.create() requires email, which now identifies the buyer; phone is optional. An email or phone you already hold updates that customer. Upgrading: pass email on every customers.create() call.
  • Breaking: a 403 is KycRequiredError only when its body carries status_code. Any other 403 is the new PermissionDeniedError. Upgrading: code that caught KycRequiredError for every 403 should also catch PermissionDeniedError (or the base SuqoError).
  • Breaking: Product.description, termsAndConditions, featuresAndBenefits, Plan.description, ProductVat.vatType and ProductVat.vatPercentage are now | null, and every field of Subscription.product is string | null — the API sends null for them. Upgrading: handle null where you read these as plain strings.
  • Breaking: BillingPeriod.offers is typed Offer[] instead of unknown[].
  • Product.type, ProductVat.vatType and BillingPeriod.intervalType list their known values for autocomplete, while still accepting a value the API adds later.
  • subscriptions.create() is documented as legacy — prefer checkoutSessions.create(). A buyer may hold one live recurring subscription per product; an inactive one is restarted with subscriptions.renew(), not by creating a new one.

Added

  • checkoutSessions.create({ items, returnUrl, customerId? }) — the recommended way to collect payment: one to ten catalogue or partner-priced items in one checkout. Never retried automatically; rate-limited to 20 a minute. See Collect payments.
  • checkoutSessions.retrieve(id) — reads an open session, including its sessionType.
  • subscriptions.retrieve(id) and subscriptions.renew(subscriptionId).
  • Webhook management: webhooks.list(), create(), retrieve(), replace() (PUT), update() (PATCH), delete(), retrieveSecret() and testDelivery(). webhooks.verify() is unchanged.
  • PermissionDeniedError, plus the new model types (CheckoutSession, CheckoutSessionResponse, CreateCheckoutSessionParams, CheckoutItemInput, Webhook, WebhookSecret, Offer, …).

Fixed

  • A 400 whose body is a bare list of messages (cancel, resume, renew, duplicate subscription) surfaces those messages as ValidationError.message instead of "Validation failed.".
  • Every method that takes an id in the path rejects an empty, "." or ".." id with SuqoConfigError before any request — cancel("..") used to POST to /api/v1/cancel/. The webhook methods also reject "secret".
  • RateLimitError.retryAfter is filled from the wait the API writes into its message when no Retry-After header is sent — which is how the API's rate limit answers today.

1.1.0 - 2026-09-24

A deliberate exception to the MAJOR rule. The three type changes under Changed are technically SDK-only breaking changes, but each corrects a type that never matched what the API sends, so they ship as a minor. Upgrading from 1.0.0 may need the small code changes noted under each.

Added

  • customers.create({ phone, fullName?, email?, address? }) — records a customer without opening a subscription. A phone you already hold updates that customer instead, so it's safe to retry yourself; the SDK never retries it automatically.
  • customers.update(id, { fullName?, email?, address? }) — updates only the given fields; "" clears one. The phone can't be changed.
  • CreateCustomerParams, UpdateCustomerParams and ProductImage types exported.

Changed

  • Breaking: Customer.id is a string (e.g. "cus_1ce18d624"), not a number — the API never sent an integer, and the number type made customers.retrieve() uncallable with a real id. Upgrading: switch customer ids typed as number to string.
  • Breaking: Customer.address added (string | null) — it was on the wire but missing from the type. Upgrading: add address: null to any Customer objects you build yourself.
  • Breaking: Product.productImage is ProductImage[] ({ image, imageOrder }), not string[] — the API sends image objects. 1.0.0 passed them through untouched as { image, image_order }; 1.1.0 types them and renames image_order to imageOrder. Upgrading: use productImage[i].image where you used productImage[i] as a URL, and imageOrder where you read image_order.

Fixed

  • customers.retrieve() / update() reject an empty, "." or ".." id with SuqoConfigError instead of silently hitting the wrong endpoint.
  • Missing buyerPhone/buyerEmail/fullName/address keys come back as null, never undefined.

1.0.0 - 2026-09-11

Added

  • SuqoClient — environment (sandbox/live) inferred automatically from the API key prefix, with SuqoConfigError thrown before any request on a malformed key or a conflicting baseUrl override.
  • products.list() / .autoPaging() — browse the seller's product catalog. Works before KYC.
  • subscriptions.list() / .create() / .cancel() / .updateBillingCycle() / .resume() / .autoPaging() — full subscription lifecycle, including create-time reuse of an inactive/expired subscription for the same buyer + product + billing period.
  • customers.list() / .retrieve() — read-only access to the seller's customer records.
  • webhooks.verify() — HMAC-SHA256 signature verification for inbound webhook deliveries, with replay protection via a configurable timestamp tolerance. Makes no network call.
  • Automatic retries with exponential backoff and jitter for read operations, on NetworkError, 429, and 5xx — honoring a Retry-After header when present. Writes are never auto-retried (no idempotency-key support yet on the backend — see Idempotency).
  • Full SuqoError hierarchy (SuqoConfigError, AuthenticationError, KycRequiredError, ValidationError, NotFoundError, RateLimitError, ServerError, NetworkError) — every documented failure mode normalized to a class, never a wire-shape check.
  • Dual ESM + CommonJS build with bundled .d.ts, zero runtime dependencies.

Fixed

  • Corrected the sandbox base URL (test.be.suqo.ai, which did not resolve) to the real sandbox host, test-be.suqo.ai.

On this page