API reference - Pocketsflow Docs

The Pocketsflow HTTP API lets you manage products, checkout, orders, payments, subscribers, customers, discounts, upsells, refunds, webhooks, newsletters, your Link in Bio page, images, and the partner program — all from your own systems.

Open the interactive API reference

Browse every endpoint, see request/response schemas, and try calls live at api.pocketsflow.com/docs.

The raw OpenAPI specification is served at https://api.pocketsflow.com/docs.json — import it into Postman/Insomnia or generate a typed client from it.

Base URL

Every request is made over HTTPS to:

https://api.pocketsflow.com

There is no version prefix in the path today — endpoints are addressed directly (for example GET /orders). New fields are added in a backwards-compatible way; treat unknown fields as optional and never hard-code assumptions about field order.

Authentication

Every endpoint requires authentication via the Authorization header using the Bearer scheme. Two credential types are accepted:

Credential	Format	Typical use
API key	`pk_live_…` / `pk_test_…`	Server-to-server integrations, scripts, agents.
Auth0 JWT	`Bearer eyJ…`	First-party dashboard / session-based calls.

Create an API key in the dashboard under Developers → API keys, then send it on every request:

curl https://api.pocketsflow.com/users/me \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Prefix	Mode	Data
`pk_live_…`	Live	Real products, customers, payments, and payouts.
`pk_test_…`	Test	Sandbox data for development — never charges a real card.

All data is automatically scoped to the account that owns the key (and to that key’s test/live mode) — you never pass a user id. Keys are stored hashed, can be given an expiry, and can be archived/revoked at any time; a revoked or expired key returns 401.

Treat secret API keys like passwords. Never expose them in client-side code, public repositories, or URLs. Prefer a dedicated, revocable key per integration, and rotate a key immediately if it leaks.

Authentication errors

Missing or malformed credentials return 401 with a JSON body:

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid, inactive, or has been archived"
}

Common cases: no Authorization header, a header that doesn’t start with Bearer , an empty token, and an inactive/archived/expired key.

Making requests

Send JSON bodies with Content-Type: application/json (the only exception is POST /images, which uses multipart/form-data).
Responses are JSON. IDs are Mongo ObjectId strings (24 hex characters) unless noted (Stripe subscription ids are sub_…; payment-processor ids are plan_…, pay_…, mem_…).
Timestamps are ISO 8601 UTC strings (2026-01-24T05:35:38.103Z).
Money on the Payments, Subscribers, and Orders resources is returned in major currency units (e.g. 12.1 = $12.10). Money inside a webhook payload is in the smallest unit (e.g. cents) — see Webhook events.

Pagination

List endpoints paginate in one of the following ways.

Style	Endpoints	Query params	Response envelope
Page-based	`/orders`, `/payments`, `/subscriptions/subscribers`	`page` (default `1`), `pageSize` (default `20`)	`{ <items>, pagination }`
Page + limit	`/partners/referrals`, `/partners/referrals/sales`	`page` (default `1`), `limit` (default `20`)	paginated list
None	`/customers`, `/reviews`	—	full array in one response

The page-based pagination object looks like:

{
  "totalCount": 137,
  "totalPages": 7,
  "currentPage": 1,
  "pageSize": 20,
  "hasMore": true
}

Errors

Errors use standard HTTP status codes and a JSON body carrying an error message (some endpoints also return a machine-readable code or a human message):

{ "error": "Product not found", "code": "not_found" }

Status	Meaning
`200` / `201`	Success.
`400`	Invalid request (missing/!valid parameters).
`401`	Missing, malformed, expired, or revoked credentials.
`403`	Authenticated but not permitted (e.g. unverified email sender).
`404`	Resource not found or not owned by you.
`409`	Conflict (e.g. already a partner).
`500` / `502`	Server-side error — safe to retry with backoff.

Rate limits

Requests authenticated with a valid API key get 600 requests per minute per account. Unauthenticated traffic shares a stricter per-IP allowance, so always send your key. Exceeding a limit returns 429 with a JSON body that includes retryAfter (seconds) — back off and retry after that delay. Beyond that, use reasonable concurrency, back off on 5xx, and cache where you can. Some endpoints have their own caps — for example POST /newsletters/send accepts at most 100 recipients per request.

Endpoint catalog

Everything below is available with an API key. Full request/response schemas live in the interactive reference; the most important response shapes are shown here.

Products

Method	Path	Description
`GET`	`/products`	List all products.
`POST`	`/products`	Create a product. Requires `name`, `price`.
`GET`	`/products/{id}`	Get a product by id.
`POST`	`/products/update/{id}`	Update a product.
`DELETE`	`/products/{id}`	Delete a product.

POST /products accepts (among others) name, price, description, subtitle, published, slug, thumbnail, images[], payWant, minPrice, maxPrice, showSales, showReviews, refundPolicy, hasFirstName, hasLastName.

Checkout

Method	Path	Description
`POST`	`/checkout/sessions`	Create a hosted checkout session and redirect the buyer to pay.

curl https://api.pocketsflow.com/checkout/sessions \
  -H "Authorization: Bearer pk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "665f1c2a9b3e4a0012ab34cd",
    "successUrl": "https://acme.com/thanks",
    "cancelUrl": "https://acme.com/pricing",
    "customerEmail": "buyer@example.com",
    "discountCode": "LAUNCH20"
  }'

{
  "id": "cs_665f1c2a9b3e4a0012ab99aa",
  "url": "https://acme.pocketsflow.com/checkout/cs_665f1c2a9b3e4a0012ab99aa"
}

Required: productId, successUrl, cancelUrl. Optional: customerEmail, discountCode, metadata (echoed back on the resulting order.completed webhook).

Orders

Method	Path	Description
`GET`	`/orders`	List orders. Filters: `startDate`, `endDate`, `productId`, `page`, `pageSize`.
`GET`	`/orders/{id}`	Get an order by id.
`GET`	`/orders/subscriptions/{id}`	Get a subscriber with its subscription offer, customer, live `status`, and full `payments` history. `{id}` is the SubscriptionCustomer `_id`.

{
  "orders": [
    {
      "_id": "6a43ce05fae6c4f0cb5a2193",
      "buyerEmail": "buyer@example.com",
      "gross": 12.1,
      "net": 8.46,
      "taxes": 2.1,
      "createdAt": "2026-01-24T05:35:38.103Z",
      "product": { "_id": "665f1c2a9b3e4a0012ab34cd", "name": "Starter Kit" },
      "customer": { "_id": "665f1c2a9b3e4a0012abaa11", "buyerEmail": "buyer@example.com" }
    }
  ],
  "pagination": { "totalCount": 42, "totalPages": 3, "currentPage": 1, "pageSize": 20, "hasMore": true }
}

Payments

The unified payment ledger — one-time product purchases and subscription charges (initial + every renewal) in a single resource. Every payment is a Sale.

Method	Path	Description
`GET`	`/payments`	List payments. Filters: `type` (`one_time` \| `subscription` \| `all`), `startDate`, `endDate`, `productId`, `subscriptionId`, `page`, `pageSize`.
`GET`	`/payments/{id}`	Get a payment by id. Pass `?live=true` to also fetch the authoritative live payment from the payment processor as `whopLive`.

A single Payment object:

{
  "_id": "665f1c2a9b3e4a0012ab34cd",
  "isSubscription": true,
  "billingReason": "renewal",
  "amount": 12.1,
  "grossAmount": 12.1,
  "amountBeforeTax": 10,
  "taxAmount": 2.1,
  "currency": "usd",
  "buyerEmail": "buyer@example.com",
  "firstName": "Jane",
  "lastName": "Buyer",
  "isRefunded": false,
  "isDisputed": false,
  "productId": "",
  "subscriptionId": "665f1c2a9b3e4a0012ab7788",
  "whopPaymentId": "pay_rehv02B3gdIZT0",
  "whopPlanId": "plan_vlD50mPbsqJLp",
  "whopMembershipId": "mem_UCTD32gDLGTgb",
  "createdAt": "2026-01-24T05:35:38.103Z"
}

boolean

true for subscription payments (initial + renewals); false for one-time product purchases.

string

Present only on subscription payments: initial for the first charge that activates the membership, renewal for every recurring charge after it.

string

Set on one-time purchases; empty on subscription payments (use subscriptionId instead).

string

The processor’s receipt, plan, and membership ids backing the sale. whopMembershipId is present on subscription payments only.

GET /payments returns { payments: [Payment], pagination }. GET /payments/{id}?live=true returns a PaymentDetail:

{
  "payment": {
    "_id": "665f1c2a9b3e4a0012ab34cd",
    "isSubscription": true,
    "billingReason": "renewal",
    "amount": 12.1,
    "amountBeforeTax": 10,
    "taxAmount": 2.1,
    "currency": "usd",
    "net": 8.46,
    "fee": 0.94,
    "metadata": { "id": "pay_rehv02B3gdIZT0", "status": "paid", "...": "raw stored processor payload" }
  },
  "product": null,
  "subscription": { "_id": "665f1c2a9b3e4a0012ab7788", "name": "Pro Membership", "price": 29, "frequency": "monthly" },
  "customer": { "_id": "665f1c2a9b3e4a0012abaa11", "buyerEmail": "buyer@example.com" },
  "whop": { "id": "pay_rehv02B3gdIZT0", "total": 12.1, "subtotal": 10 },
  "whopLive": { "id": "pay_rehv02B3gdIZT0", "status": "paid", "amount_after_fees": 8.46 }
}

net = amountBeforeTax − affiliateCut − stripeFee; fee is the processor fee. whopLive is null if the live lookup failed — the stored whop block still applies, so ?live=true never fails the request.

Subscriptions and subscribers

Two distinct concepts: a subscription offer is the recurring product you sell; a subscriber is a buyer’s membership in one of those offers.

Method	Path	Description
`POST`	`/subscriptions`	Create a subscription offer. Requires `name`, `price`, and `frequency` (`weekly`, `monthly`, or `yearly`).
`GET`	`/subscriptions`	List your subscription offers.
`GET`	`/subscriptions/{id}`	Get a subscription offer by id.
`GET`	`/subscriptions/subscribers`	List subscribers. Filters: `status`, `buyerEmail` (alias `email`), `subscriptionId`, `page`, `pageSize`.
`GET`	`/subscriptions/subscribers/{id}`	Get a subscriber + `subscription`, `customer`, live `status`, and full `payments` history. `?live=true` adds `whopMembership`.
`POST`	`/subscriptions/{id}/cancel`	Cancel a subscriber’s subscription now. `{id}` is the Stripe subscription id (`sub_…`).
`POST`	`/subscriptions/{id}/pause`	Pause collection on a subscription (`sub_…`).
`POST`	`/subscriptions/{id}/resume`	Resume a paused subscription (`sub_…`).

Subscription offer creation and /subscriptions/{id} accept both an API key and an Auth0 JWT. In SDK v1.2.0 and later, Node.js and TypeScript users can call pocketsflow.subscriptionOffers.create(). See the SDK guide for installation and usage; use the REST request above if your installed SDK predates v1.2.0.

A Subscriber object carries a processor-sourced live status (incomplete, incomplete_expired, trialing, active, past_due, canceled, unpaid, succeeded, refunded, paused) and the joined offer:

{
  "_id": "665f1c2a9b3e4a0012abccdd",
  "buyerEmail": "buyer@example.com",
  "status": "active",
  "active": true,
  "whopSubscriptionId": "plan_vlD50mPbsqJLp",
  "subscriptionId": "665f1c2a9b3e4a0012ab7788",
  "firstName": "Jane",
  "lastName": "Buyer",
  "country": "NL",
  "createdAt": "2026-01-24T05:35:38.103Z",
  "subscription": { "_id": "665f1c2a9b3e4a0012ab7788", "name": "Pro Membership", "price": 29, "frequency": "monthly" }
}

GET /subscriptions/subscribers/{id}?live=true:

{
  "subscriber": { "_id": "665f1c2a9b3e4a0012abccdd", "status": "active", "buyerEmail": "buyer@example.com" },
  "subscription": { "_id": "665f1c2a9b3e4a0012ab7788", "name": "Pro Membership", "price": 29, "frequency": "monthly" },
  "customer": { "_id": "665f1c2a9b3e4a0012abaa11", "buyerEmail": "buyer@example.com" },
  "status": "active",
  "payments": [
    { "_id": "665f...01", "billingReason": "initial", "amount": 29, "createdAt": "2026-05-24T10:00:00.000Z" },
    { "_id": "665f...02", "billingReason": "renewal", "amount": 29, "createdAt": "2026-06-24T10:00:00.000Z" }
  ],
  "whopMembership": { "id": "mem_UCTD32gDLGTgb", "status": "active", "valid": true }
}

Discounts

Method	Path	Description
`GET`	`/discounts`	List discounts.
`POST`	`/discounts`	Create a discount. Requires `name`, `code`, `value`, `mainProductIds`.
`GET`	`/discounts/{id}`	Get a discount by id.
`POST`	`/discounts/{id}`	Update a discount (full update — send every field you want to keep).
`DELETE`	`/discounts/{id}`	Delete a discount.
`GET`	`/discounts/apply/{discountCode}/{productId}`	Public (no API key) — validate a code against a product; returns the discount or `404`.
`GET`	`/discounts/check-product/{productId}`	Public (no API key) — returns `true`/`false` whether any discount targets the product.

valueType is percentage (default) or fixed; optional active, expiration.

Upsells

Method	Path	Description
`GET`	`/upsells`	List upsells.
`POST`	`/upsells`	Create an upsell. Requires `mainProductIds`, `upsellProductId`, `upsellPrice`.
`GET`	`/upsells/{id}`	Get an upsell by id.
`POST`	`/upsells/{id}`	Update an upsell (full update — send every field you want to keep).
`DELETE`	`/upsells/{id}`	Delete an upsell.

Optional: name, offer, upsellDescription, primaryButtonText, secondaryButtonText, active.

Refunds

Method	Path	Description
`POST`	`/refunds`	Create a refund. Requires `orderId`; optional `amount` (partial), `reason`.
`GET`	`/refunds`	List refunds.
`GET`	`/refunds/{id}`	Get a refund by id.

Reviews

Method	Path	Description
`GET`	`/reviews`	List all your product reviews, newest first (no filters).

Webhooks

Method	Path	Description
`GET`	`/webhooks`	List webhook endpoints (secrets omitted).
`POST`	`/webhooks`	Create a webhook. Requires `url` (HTTPS), `events[]`. Returns the signing `secret`.
`GET`	`/webhooks/{id}`	Get a webhook by id.
`PATCH`	`/webhooks/{id}`	Update a webhook.
`DELETE`	`/webhooks/{id}`	Delete a webhook.
`POST`	`/webhooks/{id}/test`	Send a sample event to the endpoint.

See Webhook events for the full event list and payloads, and Authentication & security for signature verification.

Newsletters

Method	Path	Description
`GET`	`/newsletters/posts`	List posts. Filter by `status` (`draft` \| `published`).
`POST`	`/newsletters/posts`	Create a post. Requires `title`, `content`.
`GET`	`/newsletters/posts/{id}`	Get a post by id.
`POST`	`/newsletters/posts/{id}`	Update a post (sent posts can no longer be edited).
`DELETE`	`/newsletters/posts/{id}`	Delete a post.
`POST`	`/newsletters/posts/{id}/send`	Send a post to all subscribers.
`POST`	`/newsletters/send`	Send a one-off email to up to 100 recipients. See Send email.
`GET`	`/newsletters/subscribers`	List newsletter subscribers.
`GET`	`/newsletters/subscribers/{id}`	Get a subscriber by id.
`DELETE`	`/newsletters/subscribers/{id}`	Remove a subscriber.

Link in Bio (creator pages)

Method	Path	Description
`GET`	`/creator-pages`	Get your Link in Bio page.
`POST`	`/creator-pages`	Update page settings and content.
`POST`	`/creator-pages/links`	Add a link (`title`, `url` required).
`PUT`	`/creator-pages/links/{id}`	Update a link.
`DELETE`	`/creator-pages/links/{id}`	Delete a link.

Images

Method	Path	Description
`POST`	`/images`	Upload an image (`multipart/form-data`, field `file`). Returns `{ url, id }`.
`GET`	`/images`	List uploaded images.
`DELETE`	`/images/{id}`	Delete an image.

Customers

Method	Path	Description
`GET`	`/customers`	List customers (full list, deduplicated by email, with `numberOfOrders`). Filter by `productId`; sort with `sortBy` (`email` \| `country` \| `numberOfOrders` \| `createdAt`) and `sortOrder` (`asc` \| `desc`).
`GET`	`/customers/{id}`	Get a customer by id.

Account

Method	Path	Description
`GET`	`/users/me`	Get the authenticated account.

{
  "userId": "auth0|68fd3a499605389e7305cdc1",
  "email": "creator@example.com",
  "subdomain": "acme",
  "testMode": false,
  "hasSales": true,
  "createdFirstProduct": true,
  "stripeAccountId": "acct_1Nz...",
  "stripeAccountStatus": "active"
}

Use subdomain to build product/checkout URLs (https://{subdomain}.pocketsflow.com/...).

Partners

Method	Path	Description
`POST`	`/partners`	Become a partner. Returns your `referralCode`.
`GET`	`/partners`	Get your partner profile.
`POST`	`/partners/register-referral`	Record a referral signup (`referralCode`).
`GET`	`/partners/referrals`	List referred users (`page`, `limit`).
`GET`	`/partners/referrals/sales`	List sales from referred users (`page`, `limit`).
`GET`	`/partners/stats`	Live-computed signups, sales, revenue, and commission.

Connect an AI agent

Prefer to drive Pocketsflow from an AI assistant? The MCP server exposes this entire API as Model Context Protocol tools — connect Claude, Cursor, or your own agent with an API key and it can manage your account in natural language.

Building an integration?

If you’re connecting Pocketsflow to an external store or platform (for example WooCommerce), start with the Integrations section — it walks through the end-to-end pattern with code examples.

Open the interactive API reference

​Base URL

​Authentication

​Authentication errors

​Making requests

​Pagination

​Errors

​Rate limits

​Endpoint catalog

​Products

​Checkout

​Orders

​Payments

​Subscriptions and subscribers

​Discounts

​Upsells

​Refunds

​Reviews

​Webhooks

​Newsletters

​Link in Bio (creator pages)

​Images

​Customers

​Account

​Partners

​Connect an AI agent

​Building an integration?

​Related topics

Base URL

Authentication

Authentication errors

Making requests

Pagination

Errors

Rate limits

Endpoint catalog

Products

Checkout

Orders

Payments

Subscriptions and subscribers

Discounts

Upsells

Refunds

Reviews

Webhooks

Newsletters

Link in Bio (creator pages)

Images

Customers

Account

Partners

Connect an AI agent

Building an integration?

Related topics