Web SDK reference

The three packages are released together at one version. The current one is on the Web SDK page.

createCashSDK(options)#

cashsdk-web. Returns a CashSDKClient. Creating it makes no request.

Client methods#

Every method that makes a request accepts { signal } and rejects with a CashSDKError.

Wait options: timeoutMs (default 30000, at most 300000), intervalMs (first delay, default 1000, from 100 to 5000, growing to 5000), and signal. A wait keeps going through failures a retry can fix, and ends at once on sign-out, on a change of customer or when signal aborts.

Types#

type ClientSnapshot = {
  status: "idle" | "loading" | "ready" | "error" | "signed_out" | "destroyed";
  customer: { customerId: string; environment: Environment } | null;
  entitlements: EntitlementSnapshot | null;
  error: Error | null;
};

type EntitlementSnapshot = {
  customerId: string;
  environment: "sandbox" | "production";
  revision: number;
  computedAt: string;             // ISO 8601
  entitlements: readonly {
    identifier: string;           // for example "pro"
    name: string;
    active: boolean;
    rank: number | null;
    source: string;               // subscription, purchase, manual_grant, ...
    expiresAt?: string | null;    // null when it does not expire
  }[];
};

type WebSubscription = {
  productIdentifier: string;
  displayName: string | null;
  provider: string | null;        // stripe, app-store, play-store, ...
  status: string;                 // active, expired, revoked, in_grace_period, ...
  active: boolean;                // grants access right now
  expiresAt: string | null;
  autoRenew: boolean;
  trial: boolean;
};

type Offerings = {
  current: {
    id: string;
    identifier: string;
    displayName: string | null;
    packages: readonly {
      id: string;
      identifier: string;         // for example "$monthly"
      purchasable: boolean;       // this session can start a checkout for it
      product: {
        identifier: string;
        displayName: string | null;
        type: string;             // auto_renewable, non_consumable, ...
        provider: string;         // stripe, ...
        amountMinor: string | null; // integer minor units as a string, "1299" is 12.99
        currency: string | null;  // ISO 4217
        duration: string | null;  // ISO 8601, for example "P1M"
      };
    }[];
  } | null;
};

type Checkout = {
  id: string;
  provider: "stripe";
  environment: "sandbox" | "production";
  status: "pending" | "requires_action" | "complete" | "expired" | "failed" | "needs_review";
  paymentStatus: string | null;   // Stripe's: paid, unpaid, no_payment_required
  accessStatus: "check_entitlements";
  action: { type: "redirect"; url: string } | null;
  expiresAt: string | null;
};

checkout input: packageId, successUrl, cancelUrl (both on the session's origin, with no fragment; for an extension, on one of the app's allowed HTTPS origins), and optionally connectionId. The idempotency key is 16 to 128 letters, digits, _ or -. Replaying a key returns the checkout it created.

openBillingPortal input: returnUrl, on the session's origin with no fragment, at most 2,048 characters. It resolves to { url }, an https://billing.stripe.com/ link that expires within minutes.

cashsdk-web/extension#

For Manifest V3 extension pages and service workers. See Chrome extensions.

tabs is chrome.tabs, or anything with a create({ url, active }) method. The types ExtensionRuntime and ExtensionTabs describe the parts of the Chrome APIs it uses.

cashsdk-react#

CashSDKProvider({ client, children }) and the hooks useCashSDK, useCashSDKState, useCustomer, useEntitlements, useSubscriptions, useOfferings, useCheckout and useBillingPortal. See React and Next.js.

cashsdk-node#

Session scopes#

Errors#

Every failure is a CashSDKError:

Error codes#

Some input errors are also raised by the SDK before any request is sent, with status 0.

Sessions and keys

Checkout

Billing portal

Raised by the SDKs

A failure without a code of its own gets one from its status: forbidden, not_found, conflict, request_too_large, service_unavailable or internal_error.

HTTP routes#

The packages call these. Browser routes need Authorization: Bearer csk_pk_…, the X-CashSDK-Web-Session header and the page's Origin. An extension client also sends its origin in X-CashSDK-Client-Origin, which counts only when Chrome sends no Origin. Server routes need a server key and refuse any request with an Origin header.

Responses are never cached (Cache-Control: no-store), and failures are { "error": { "code", "message", "retryable", "requestId" } }.

Limits#

• Sessions last 60 to 600 seconds, default 600. Reuse one until it expires.
• Minting sessions: 20,000 a minute per server key and 120 a minute per customer, counted apart from other server calls.
• Up to 20 allowed origins per environment.
• Browser routes: 1,000 requests a minute per customer. Other server routes: 1,000 requests a minute per key.
• Billing portal sessions: 20 a minute per customer, from the browser and the server together.
• A Stripe Checkout Session started by the SDK expires after 60 minutes.
• Supported: browsers with fetch, AbortController and ES2022; Node.js 20.19+ or 22.12+; React 18 and 19.