Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 38 ยท Getting Started

The Node SDK, API Versions and Pagination

See what the official Stripe SDK adds to raw HTTP: typed methods, API version pinning, auto-pagination, expandable objects and automatic retries, with runnable stand-ins.

You can call Stripe with plain fetch, as the previous lesson showed, but almost every project uses an official library. Stripe publishes SDKs for Node.js, Python, PHP, Ruby, Java, Go and .NET. They all do the same jobs: build the request, encode the body, attach the key, retry network failures, and turn the JSON back into objects. This lesson covers the four SDK ideas that shape how you write code: method names, API versions, expanding related objects and pagination.

The stripe npm package is not available in our runner, so the SDK code below is read-only, and each idea has a runnable stand-in.

Resources and methods

The SDK mirrors the REST paths. POST /v1/customers becomes stripe.customers.create(...), GET /v1/customers/cus_1 becomes stripe.customers.retrieve("cus_1"), and so on. Most resources offer create, retrieve, update, list and sometimes del or cancel.

JavaScript
// Real SDK usage (read-only).
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

const customer = await stripe.customers.create({
  name: "Ada Lovelace",
  email: "[email protected]",
  metadata: { crm_id: "7731" },
});

const found = await stripe.customers.retrieve(customer.id);
await stripe.customers.update(customer.id, { name: "Ada King" });

Every method returns a promise, so you use await and try/catch. The SDK also lets you pass a second options argument: { idempotencyKey: "..." }, { stripeAccount: "acct_..." } for Connect, or { apiVersion: "..." } (see Idempotency and Safe Retries).

API versions

Stripe evolves its API without breaking you. Each account is pinned to an API version, named by a date such as 2025-09-30.clover. Fields keep the shape that version defines, even after Stripe ships newer ones. Upgrading is a deliberate act: test in a sandbox, then change the version in the Dashboard, or pass it in code.

Two practical rules:

  • Pin the version in code (new Stripe(key, { apiVersion: "..." })). Each SDK release is built for one version, and pinning makes behaviour predictable.
  • Webhook payloads follow the version of the endpoint, so upgrade webhook handlers and API calls together.

You can think of a version as a translation layer. The same stored payment is described differently depending on the version asked for. This stand-in shows the idea: two "versions" of the same record.

Node.js Versioned responses (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Many fields hold an ID of a related object. A PaymentIntent has customer: "cus_123", not the whole customer. Fetching the customer separately costs a second round trip. The expand parameter asks Stripe to inline the related object in the same response.

JavaScript
// Real SDK usage (read-only).
const pi = await stripe.paymentIntents.retrieve("pi_123", {
  expand: ["customer", "latest_charge"],
});
console.log(pi.customer.email);          // object, because it was expanded
console.log(pi.latest_charge.receipt_url);

You can expand up to four levels deep with dotted paths ("latest_charge.balance_transaction"). Without expand, those fields are plain strings. This stand-in shows the difference:

Node.js Expand inlines related objects (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Expand only what you need. Each expansion makes the response larger, and list endpoints cannot expand more than three levels.

Pagination

List endpoints return at most 100 objects per call (default 10). A response looks like { object: "list", data: [...], has_more: true }. To get the next page you pass starting_after with the ID of the last item you received. This is cursor-based pagination, which stays correct even if new objects appear while you page.

JavaScript
// Real SDK usage (read-only).
for await (const customer of stripe.customers.list({ limit: 100 })) {
  console.log(customer.email);   // the SDK fetches further pages automatically
}

The SDK's for await auto-pagination is convenient but can be slow for huge lists. For big exports, page manually and keep your cursor so you can resume. Here is the cursor mechanism in a stand-in:

Node.js Cursor pagination (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Automatic retries and timeouts

The SDK can retry failed network calls (maxNetworkRetries, default 1 in recent versions) and applies a request timeout (default about 80 seconds). For payments, always pair retries with idempotency keys; the SDK adds one automatically when it retries a POST. Set a shorter timeout if your web request cannot wait that long, and handle the timeout error as "outcome unknown", not as "failed".

Typing with TypeScript

The Node SDK ships TypeScript definitions: Stripe.PaymentIntent, Stripe.Customer, Stripe.Checkout.Session. Use them to type your own helpers. Types catch typos such as amout at build time, which is far cheaper than discovering them in production.

Next, a quick tour of the tools around the API: Dashboard, CLI and Workbench.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does expand: ["customer"] do on a PaymentIntent request?

    Expand inlines related objects, saving a second API call.
  2. 2. How do you fetch the next page of a list?

    Stripe uses cursor-based pagination: starting_after (or ending_before) plus has_more.
  3. 3. Why pin the API version in code?

    Each version defines field shapes. Pinning avoids surprises and lets you upgrade on your schedule.
  4. 4. The SDK throws a timeout while creating a payment. How should you treat it?

    A timeout means you do not know whether Stripe processed the request. Idempotency keys make retrying safe.

Summary

  • SDK methods mirror REST resources: stripe.customers.create, retrieve, update, list.
  • Accounts are pinned to a dated API version; pin it in code too.
  • expand inlines related objects; use it only where needed.
  • Lists use cursor pagination with starting_after and has_more.
  • A timeout means "outcome unknown"; retry with an idempotency key.

Next: Dashboard, CLI and Workbench