> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pocketsflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pocketsflow Node.js SDK

> Install and use the official Pocketsflow SDK for Node.js and TypeScript.

The official [`pocketsflow`](https://www.npmjs.com/package/pocketsflow) package
is a server-side Node.js and TypeScript client for the Pocketsflow API. It uses
the same API-key authentication and endpoint shapes documented in the
[API reference](/api-reference/introduction).

<CardGroup cols={2}>
  <Card title="Install from npm" icon="package" href="https://www.npmjs.com/package/pocketsflow">
    Add the SDK to a Node.js or TypeScript project.
  </Card>

  <Card title="View the source" icon="github" href="https://github.com/Pocketsflow/pocketsflow-sdk">
    Browse the SDK source, types, examples, and release history.
  </Card>
</CardGroup>

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install pocketsflow
  ```

  ```bash Yarn theme={null}
  yarn add pocketsflow
  ```

  ```bash pnpm theme={null}
  pnpm add pocketsflow
  ```
</CodeGroup>

## Initialize the client

Create an API key in **Developers → API keys** and keep it on your server. Use
`pk_live_...` for live data or `pk_test_...` for sandbox data.

```ts theme={null}
import { Pocketsflow } from "pocketsflow";

const pocketsflow = new Pocketsflow({
  apiKey: process.env.POCKETSFLOW_API_KEY!,
  // Optional. Defaults to https://api.pocketsflow.com.
  baseUrl: "https://api.pocketsflow.com",
  // Optional. Defaults to 30 seconds.
  timeout: 30_000,
});
```

<Warning>
  Never expose an API key in browser code, a mobile app, a public repository, or
  a URL. Call the SDK from a trusted server or server-side function.
</Warning>

## Read data

Resources expose typed `list()` and `get()` methods:

```ts theme={null}
const me = await pocketsflow.users.me();
const products = await pocketsflow.products.list();
const product = await pocketsflow.products.get("product_id");
const customers = await pocketsflow.customers.list();
const { orders, pagination } = await pocketsflow.orders.list({
  page: 1,
  pageSize: 20,
});
```

The main namespaces are `products`, `variants`, `orders`, `customers`,
`reviews`, `discounts`, `upsells`, `subscriptions`, `subscriptionOffers`,
`webhooks`, `users`, `checkout`, and `refunds`.

## Create products and webhooks

```ts theme={null}
const product = await pocketsflow.products.create({
  name: "Premium Course",
  description: "Everything a buyer needs to get started.",
  price: 49.99,
});

await pocketsflow.products.update(product._id, {
  price: 59.99,
});

const webhook = await pocketsflow.webhooks.create({
  url: "https://example.com/webhooks/pocketsflow",
  events: ["order.completed", "order.refunded"],
  description: "Pocketsflow events",
});
```

## Create subscription offers

Use `subscriptionOffers` for the recurring products you sell. Use
`subscriptions` for the buyers who hold those offers; they are different
resources.

```ts theme={null}
const offer = await pocketsflow.subscriptionOffers.create({
  name: "Pro Membership",
  description: "Access to all premium content.",
  price: 29,
  frequency: "monthly",
  trialPeriod: 7,
  redirectBackUrl: "https://example.com/account/billing",
});

const offers = await pocketsflow.subscriptionOffers.list();
const sameOffer = await pocketsflow.subscriptionOffers.get(offer._id);
```

`frequency` must be `weekly`, `monthly`, or `yearly`. The required fields are
`name`, `price`, and `frequency`; the SDK also supports the optional offer
fields defined in its TypeScript types.

<Note>
  `subscriptionOffers.create` is included in the SDK source's current v1.2.0
  release. If npm still installs an older version in your environment, upgrade
  when that release is published or call `POST /subscriptions` directly until
  then.
</Note>

## Create checkout sessions

Pass either a one-time product id or a subscription-offer id as `productId`:

```ts theme={null}
const session = await pocketsflow.checkout.create({
  productId: offer._id,
  successUrl: "https://example.com/welcome",
  cancelUrl: "https://example.com/pricing",
  customerEmail: "buyer@example.com",
  metadata: { plan: "pro" },
});

// Redirect the buyer to session.url.
console.log(session.url);
```

## Manage subscribers

The `subscriptions` namespace manages buyer subscriptions and supports listing,
retrieval, cancellation, and refunds. The subscriber-specific lifecycle methods
are also available through the API endpoints documented in the
[subscriptions quickstart](/api-reference/subscriptions-quickstart).

```ts theme={null}
const subscribers = await pocketsflow.subscriptions.list({
  page: 1,
  pageSize: 20,
});

const subscriber = await pocketsflow.subscriptions.get("subscription_id");
await pocketsflow.subscriptions.cancel("stripe_subscription_id");
```

## Handle errors

SDK calls reject when the API returns a non-2xx response:

```ts theme={null}
try {
  await pocketsflow.products.get("missing_product");
} catch (error) {
  console.error("Pocketsflow request failed:", error);
}
```

For endpoint details, request schemas, response types, and webhook events, use
the [interactive API reference](https://api.pocketsflow.com/docs).