A brand-authenticated REST API for your Nestuge store. Read products, transactions, hub members and a product’s customers, import members and customers, generate checkout links and subscribe to webhooks.
The Nestuge API lets you connect your store to the systems you already run: accounting, email and CRM, automations, custom checkout flows and AI agents. It is plain HTTPS and JSON, and every request is authenticated with a brand API key.
Every response shares one envelope: status, message and data.
List endpoints paginate with limit and cursor, and return items, hasMore and nextCursor.
Every request carries a brand API key in the x-nestuge-api header. Create keys in the dashboard under Settings → Developer.
Keys begin with nk_live_. The nk_test_ prefix marks keys created outside production.
Each key has scopes, such as products:read or webhooks:write. Every endpoint below lists the scope it needs.
GET /ping verifies a key and returns its brand and scopes.
Keep keys server-side and never ship them in client code. If a key leaks, revoke it in the dashboard and create a new one; the old key stops working at once.
Nestuge runs an MCP server at https://nestuge.com/api/mcp, on the main domain rather than the dashboard. Any MCP client can connect, so an assistant can work inside a creator's account: reading products, customers and sales, and creating things with them.
No API key. Clients register automatically (RFC 7591) and the creator approves access in the browser with OAuth 2.1 and PKCE.
OAuth access tokens also work on the REST endpoints, limited to the scopes that were approved.
Connecting an agent requires the Plus plan. Creators can revoke an app at any time under Settings → Developers → Apps.
import { constructEvent } from '@nestuge/sdk';const event = await constructEvent({ payload: rawRequestBody, // the raw, unmodified body string signature: request.headers['x-nestuge-signature'], secret: process.env.NESTUGE_WEBHOOK_SECRET,});if (event.type === 'transaction.succeeded') { // grant access, send a receipt, update your books}
Resources
The API is plain HTTPS and JSON, so any HTTP client works. For JavaScript and TypeScript there is an official SDK, @nestuge/sdk: typed, no runtime dependencies, and it runs on Node.js 18+, Bun, Deno and edge runtimes. It includes retries, cursor helpers, typed errors and webhook verification.
Install
npm install @nestuge/sdk
quickstart.ts
import Nestuge from '@nestuge/sdk';const nestuge = new Nestuge({ apiKey: process.env.NESTUGE_API_KEY });const products = await nestuge.products.list({ limit: 20 });for (const product of products.items) { console.log(product.title, product.type);}
Bulk-imports members into the hub. Send records as an array of objects; each object is one person, keyed by checkout-field id. Hubs collect only fullName and email, both required. Optionally set plan to a membership tier id (e.g. ti_abc123) to place members on a paid tier; omit for the free tier. Queues the import and returns how many records were accepted.
Creates a payment link for the given items and returns a link the customer can open to complete payment. Accepts the same payload as the web checkout. Every item must belong to the authenticated brand.
Confirms the status of a transaction by re-checking it with the payment provider, then returns the transaction. Safe to call repeatedly (idempotent) — use it to reconcile a payment when you have not yet received, or want to double-check, the transaction.succeeded webhook. The transaction must belong to the authenticated brand; 404 otherwise.
Authenticated health check. Returns the resolved brand and granted scopes so developers can confirm their key works. Any valid key may call it (no scope required).
Bulk-imports customers into the product. Send records as an array of objects; each object is one person, keyed by checkout-field id. fullName and email are always required; include any other field the product collects by its id (list them from checkoutFields on the product — each id is the field’s formData key, auto-derived from its label). Optionally set plan to a payment plan id (e.g. pl_abc123) to assign customers to a plan; omit for the default plan. Queues the import and returns how many records were accepted.