Nestuge
Sign inStart for free

Developer API

v0.1.0

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.

Get your API keys

Base URL

https://nestuge.com/api/v1 # Production
Auth headerx-nestuge-api
Key prefixesnk_live_ · nk_test_
FormatJSON over HTTPS
MCP servernestuge.com/api/mcp

Introduction

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.
Response envelope
{  "status": "success",  "message": "List products succeeded",  "data": {    "items": [],    "hasMore": false,    "nextCursor": null  }}
Your first request
curl https://nestuge.com/api/v1/products?limit=20 \  -H "x-nestuge-api: nk_live_your_key"

Authentication

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.
Verify a key
curl https://nestuge.com/api/v1/ping \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "pong",  "data": {    "ok": true,    "brandID": "br_a1b2c3d4e5",    "scopes": [      "products:read",      "customers:read",      "webhooks:write"    ]  }}

AI agents (MCP)

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.
mcp.json
{  "mcpServers": {    "nestuge": {      "url": "https://nestuge.com/api/mcp"    }  }}
REST with an OAuth token
curl https://nestuge.com/api/v1/products \  -H "Authorization: Bearer <oauth_access_token>"

Webhook events

Register an HTTPS endpoint with POST /webhooks or from the dashboard, and pick the events you want. The signing secret is returned once, at creation.

  • Each delivery carries an X-Nestuge-Signature header of the form sha256=<hex>: an HMAC-SHA256 of the raw request body with your secret.
  • Verify against the raw body. Re-serialised JSON will not match.
  • Respond with a 2xx quickly and do the work afterwards. Failed deliveries can be inspected and resent.
transaction.succeededtransaction.failedpayout.settledsubscription.renewedsubscription.expiredsubscription.completedsubscription.pausedsubscription.resumedmember.joinedmember.removed
Event envelope
{  "id": "whd_a1b2c3d4e5",  "type": "transaction.succeeded",  "created": "2026-11-06T18:40:11.000Z",  "data": {    "txref": "a1b2c3d4e5",    "type": "registration",    "status": "successful",    "amount": 5000,    "currency": "USD",    "customer": { "name": "Ada Nwosu", "email": "ada@example.com" },    "createdAt": "2026-11-06T18:40:09.000Z",    "resourceID": "pr_a1b2c3d4e5",    "metadata": {}  }}
Verify a signature
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);}
GitHubgithub.com/nestuge/nestuge-sdknpmnpmjs.com/package/@nestuge/sdkPartner programBuild an integration and get listed

Hubs

List hub members

GET/hubs/{hubID}/members

Lists a hub's members (memberships), newest first.

Scope: customers:read

Path parameters

hubIDstringrequired

Query parameters

limitstringoptional
cursorstringoptional
Request
curl "https://nestuge.com/api/v1/hubs/a1b2c3d4e5/members" \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "items": [      {        "membershipId": "a1b2c3d4e5",        "name": "Ada Lovelace",        "email": "ada@example.com",        "phone": "+2348012345678",        "hubID": "a1b2c3d4e5",        "status": "active",        "plan": "string",        "joinedAt": "2026-07-06T10:00:00.000Z"      }    ],    "hasMore": true,    "nextCursor": "a1b2c3d4e5"  }}

Get a hub member

GET/hubs/{hubID}/members/{id}

Returns a single hub membership by its membership id.

Scope: customers:read

Path parameters

hubIDstringrequired
idstringrequired
Request
curl "https://nestuge.com/api/v1/hubs/a1b2c3d4e5/members/a1b2c3d4e5" \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "membershipId": "a1b2c3d4e5",    "name": "Ada Lovelace",    "email": "ada@example.com",    "phone": "+2348012345678",    "hubID": "a1b2c3d4e5",    "status": "active",    "plan": "string",    "joinedAt": "2026-07-06T10:00:00.000Z"  }}

Import members to a hub

POST/hubs/{hubID}/members/import

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.

Scope: customers:write

Path parameters

hubIDstringrequired

Body parameters

records[]array of objectrequired
planstringoptional
Request
curl -X POST "https://nestuge.com/api/v1/hubs/a1b2c3d4e5/members/import" \  -H "x-nestuge-api: nk_live_your_key" \  -H "Content-Type: application/json" \  -d '{    "records": [      {}    ]  }'
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "queued": true,    "count": 10  }}

Payments

Generate a payment link

POST/payment-links

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.

Scope: checkout:write

Body parameters

items[]array of objectrequired
items[].idstringrequired
items[].planstringrequired
items[].typestringrequired
items[].hubIDstringoptional
items[].affiliatestringoptional
items[].selected[]array of stringoptional
items[].countnumberoptional
items[].customAmountnumberoptional
formobjectrequired
form.formDataobjectrequired
form.formData.fullNamestringrequired
form.formData.emailstringrequired
form.formData.phonestringoptional
form.guests[]array of objectoptional
form.guests[].idstringrequired
form.guests[].fullNamestringrequired
form.guests[].emailstringrequired
currencystringoptional
couponstringoptional
countryCodestringoptional
addons[]array of stringoptional
bookingobjectoptional
addressobjectoptional
deliveryLocationstringoptional
pickupLocationstringoptional
redirectUrlstringoptional
metadataobjectoptional
utmRefstringoptional
adClickIDstringoptional
adTypestringoptional
checkoutOtpVerificationSkippedbooleanoptional
receive_emailsbooleanoptional
Request
curl -X POST "https://nestuge.com/api/v1/payment-links" \  -H "x-nestuge-api: nk_live_your_key" \  -H "Content-Type: application/json" \  -d '{    "items": [      {        "id": "a1b2c3d4e5",        "plan": "string",        "type": "string",        "hubID": "a1b2c3d4e5",        "affiliate": "string",        "selected": [          "string"        ],        "count": 10,        "customAmount": 5000      }    ],    "form": {      "formData": {        "fullName": "Ada Lovelace",        "email": "ada@example.com",        "phone": "+2348012345678"      },      "guests": [        {          "id": "a1b2c3d4e5",          "fullName": "Ada Lovelace",          "email": "ada@example.com"        }      ]    }  }'
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "link": "string"  }}

Verify a payment

POST/payments/verify

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.

Scope: checkout:write

Body parameters

txrefstringrequired
Request
curl -X POST "https://nestuge.com/api/v1/payments/verify" \  -H "x-nestuge-api: nk_live_your_key" \  -H "Content-Type: application/json" \  -d '{    "txref": "string"  }'
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "txref": "string",    "type": "string",    "status": "active",    "amount": 5000,    "currency": "USD",    "customer": {      "name": "Ada Lovelace",      "email": "ada@example.com"    },    "createdAt": "2026-07-06T10:00:00.000Z",    "resourceID": "a1b2c3d4e5",    "metadata": {}  }}

Ping

Verify an API key

GET/ping

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).

Scope: none

No parameters.

Request
curl "https://nestuge.com/api/v1/ping" \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "ok": true,    "brandID": "a1b2c3d4e5",    "scopes": [      "products:read"    ]  }}

Products

List products

GET/products

Lists the brand's products (all types), newest first.

Scope: products:read

Query parameters

limitstringoptional
cursorstringoptional
Request
curl "https://nestuge.com/api/v1/products" \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "items": [      {        "id": "a1b2c3d4e5",        "type": "string",        "status": "active",        "title": "Design masterclass",        "description": "A hands-on class covering the basics.",        "imageUrl": "https://example.com/image.png",        "url": "https://example.com/webhooks/nestuge",        "visibility": "string",        "isFree": true,        "keywords": [          "string"        ],        "createdAt": "2026-07-06T10:00:00.000Z",        "updatedAt": "2026-07-06T10:00:00.000Z",        "event": {          "eventType": "string",          "venue": "Lagos, Nigeria",          "dateTime": "2026-07-06T10:00:00.000Z",          "endDate": "2026-07-06T10:00:00.000Z"        }      }    ],    "hasMore": true,    "nextCursor": "a1b2c3d4e5"  }}

Get a product

GET/products/{id}

Returns a single product owned by the brand, including its pricing tiers and content items.

Scope: products:read

Path parameters

idstringrequired
Request
curl "https://nestuge.com/api/v1/products/a1b2c3d4e5" \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "id": "a1b2c3d4e5",    "type": "string",    "status": "active",    "title": "Design masterclass",    "description": "A hands-on class covering the basics.",    "imageUrl": "https://example.com/image.png",    "url": "https://example.com/webhooks/nestuge",    "visibility": "string",    "isFree": true,    "keywords": [      "string"    ],    "createdAt": "2026-07-06T10:00:00.000Z",    "updatedAt": "2026-07-06T10:00:00.000Z",    "event": {      "eventType": "string",      "venue": "Lagos, Nigeria",      "dateTime": "2026-07-06T10:00:00.000Z",      "endDate": "2026-07-06T10:00:00.000Z"    },    "tiers": [      {        "id": "a1b2c3d4e5",        "name": "Ada Lovelace",        "type": "string",        "price": {          "amount": 5000,          "currency": "USD"        },        "discount": {          "amount": 5000,          "currency": "USD"        },        "recurrence": {          "periodic": "string",          "count": 10,          "interval": 10        },        "perks": [          "string"        ],        "buttonText": "string",        "timeBound": "2026-07-06T10:00:00.000Z",        "slots": 10,        "noOfTickets": 10,        "itemIDs": [          "string"        ],        "isDefault": true,        "status": "active",        "archived": true      }    ],    "items": [      {        "id": "a1b2c3d4e5",        "type": "string",        "title": "Design masterclass",        "description": "A hands-on class covering the basics.",        "image": "string",        "duration": 30,        "isAddon": true,        "parentId": "a1b2c3d4e5",        "price": {          "amount": 5000,          "currency": "USD"        }      }    ],    "checkoutFields": [      {        "id": "a1b2c3d4e5",        "label": "string",        "type": "string",        "required": true,        "options": [          "string"        ]      }    ]  }}

List a product's customers

GET/products/{id}/customers

Lists the product's active customers (purchasers), newest first.

Scope: customers:read

Path parameters

idstringrequired

Query parameters

limitstringoptional
cursorstringoptional
Request
curl "https://nestuge.com/api/v1/products/a1b2c3d4e5/customers" \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "items": [      {        "membershipId": "a1b2c3d4e5",        "name": "Ada Lovelace",        "email": "ada@example.com",        "phone": "+2348012345678",        "hubID": "a1b2c3d4e5",        "status": "active",        "plan": "string",        "joinedAt": "2026-07-06T10:00:00.000Z"      }    ],    "hasMore": true,    "nextCursor": "a1b2c3d4e5"  }}

Import customers to a product

POST/products/{id}/customers/import

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.

Scope: customers:write

Path parameters

idstringrequired

Body parameters

records[]array of objectrequired
planstringoptional
Request
curl -X POST "https://nestuge.com/api/v1/products/a1b2c3d4e5/customers/import" \  -H "x-nestuge-api: nk_live_your_key" \  -H "Content-Type: application/json" \  -d '{    "records": [      {}    ]  }'
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "queued": true,    "count": 10  }}

Transactions

List transactions

GET/transactions

Lists the brand's transactions, newest first.

Scope: transactions:read

Query parameters

limitstringoptional
cursorstringoptional
Request
curl "https://nestuge.com/api/v1/transactions" \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "items": [      {        "txref": "string",        "type": "string",        "status": "active",        "amount": 5000,        "currency": "USD",        "customer": {          "name": "Ada Lovelace",          "email": "ada@example.com"        },        "createdAt": "2026-07-06T10:00:00.000Z",        "resourceID": "a1b2c3d4e5",        "metadata": {}      }    ],    "hasMore": true,    "nextCursor": "a1b2c3d4e5"  }}

Get a transaction

GET/transactions/{id}

Returns a single transaction by its reference.

Scope: transactions:read

Path parameters

idstringrequired
Request
curl "https://nestuge.com/api/v1/transactions/a1b2c3d4e5" \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "txref": "string",    "type": "string",    "status": "active",    "amount": 5000,    "currency": "USD",    "customer": {      "name": "Ada Lovelace",      "email": "ada@example.com"    },    "createdAt": "2026-07-06T10:00:00.000Z",    "resourceID": "a1b2c3d4e5",    "metadata": {}  }}

Webhooks

List webhook endpoints

GET/webhooks

Lists the brand's webhook endpoints.

Scope: webhooks:write

Query parameters

limitstringoptional
cursorstringoptional
Request
curl "https://nestuge.com/api/v1/webhooks" \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "items": [      {        "id": "a1b2c3d4e5",        "url": "https://example.com/webhooks/nestuge",        "events": [          "transaction.succeeded"        ],        "status": "active",        "description": "A hands-on class covering the basics.",        "createdAt": "2026-07-06T10:00:00.000Z",        "updatedAt": "2026-07-06T10:00:00.000Z"      }    ],    "hasMore": true,    "nextCursor": "a1b2c3d4e5"  }}

Create a webhook endpoint

POST/webhooks

Registers an endpoint URL. The signing secret is returned once in this response and never again.

Scope: webhooks:write

Body parameters

urlstringrequired
events[]One of: transaction.succeeded, transaction.failed, payout.settled, subscription.renewed, subscription.expired, subscription.completed, subscription.paused, subscription.resumed, member.joined, member.removedarray of enumrequired
descriptionstringoptional
Request
curl -X POST "https://nestuge.com/api/v1/webhooks" \  -H "x-nestuge-api: nk_live_your_key" \  -H "Content-Type: application/json" \  -d '{    "url": "https://example.com/webhooks/nestuge",    "events": [      "transaction.succeeded"    ]  }'
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "id": "a1b2c3d4e5",    "url": "https://example.com/webhooks/nestuge",    "events": [      "transaction.succeeded"    ],    "status": "active",    "description": "A hands-on class covering the basics.",    "createdAt": "2026-07-06T10:00:00.000Z",    "updatedAt": "2026-07-06T10:00:00.000Z",    "signingSecret": "string"  }}

Get a webhook endpoint

GET/webhooks/{id}
Scope: webhooks:write

Path parameters

idstringrequired
Request
curl "https://nestuge.com/api/v1/webhooks/a1b2c3d4e5" \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "id": "a1b2c3d4e5",    "url": "https://example.com/webhooks/nestuge",    "events": [      "transaction.succeeded"    ],    "status": "active",    "description": "A hands-on class covering the basics.",    "createdAt": "2026-07-06T10:00:00.000Z",    "updatedAt": "2026-07-06T10:00:00.000Z"  }}

Update a webhook endpoint

PATCH/webhooks/{id}
Scope: webhooks:write

Path parameters

idstringrequired

Body parameters

urlstringoptional
events[]One of: transaction.succeeded, transaction.failed, payout.settled, subscription.renewed, subscription.expired, subscription.completed, subscription.paused, subscription.resumed, member.joined, member.removedarray of enumoptional
statusOne of: active, disabledenumoptional
descriptionstringoptional
Request
curl -X PATCH "https://nestuge.com/api/v1/webhooks/a1b2c3d4e5" \  -H "x-nestuge-api: nk_live_your_key" \  -H "Content-Type: application/json" \  -d '{}'
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "id": "a1b2c3d4e5",    "url": "https://example.com/webhooks/nestuge",    "events": [      "transaction.succeeded"    ],    "status": "active",    "description": "A hands-on class covering the basics.",    "createdAt": "2026-07-06T10:00:00.000Z",    "updatedAt": "2026-07-06T10:00:00.000Z"  }}

Delete a webhook endpoint

DEL/webhooks/{id}
Scope: webhooks:write

Path parameters

idstringrequired
Request
curl -X DELETE "https://nestuge.com/api/v1/webhooks/a1b2c3d4e5" \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "id": "a1b2c3d4e5",    "deleted": false  }}

Send a test webhook event

POST/webhooks/test

Synthesizes a sample event and delivers it through the real signed/retried/logged pipeline as a sample delivery.

Scope: webhooks:write

Body parameters

eventTypeOne of: transaction.succeeded, transaction.failed, payout.settled, subscription.renewed, subscription.expired, subscription.completed, subscription.paused, subscription.resumed, member.joined, member.removedenumrequired
endpointIDstringoptional
Request
curl -X POST "https://nestuge.com/api/v1/webhooks/test" \  -H "x-nestuge-api: nk_live_your_key" \  -H "Content-Type: application/json" \  -d '{    "eventType": "transaction.succeeded"  }'
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "created": 10  }}

List webhook deliveries

GET/webhooks/deliveries
Scope: webhooks:write

Query parameters

limitstringoptional
cursorstringoptional
Request
curl "https://nestuge.com/api/v1/webhooks/deliveries" \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "items": [      {        "id": "a1b2c3d4e5",        "endpointID": "a1b2c3d4e5",        "eventType": "transaction.succeeded",        "resourceType": "transaction",        "resourceID": "a1b2c3d4e5",        "status": "pending",        "attempts": 10,        "responseCode": 10,        "mode": "live",        "createdAt": "2026-07-06T10:00:00.000Z",        "deliveredAt": "2026-07-06T10:00:00.000Z"      }    ],    "hasMore": true,    "nextCursor": "a1b2c3d4e5"  }}

Get a webhook delivery

GET/webhooks/deliveries/{id}
Scope: webhooks:write

Path parameters

idstringrequired
Request
curl "https://nestuge.com/api/v1/webhooks/deliveries/a1b2c3d4e5" \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "id": "a1b2c3d4e5",    "endpointID": "a1b2c3d4e5",    "eventType": "transaction.succeeded",    "resourceType": "transaction",    "resourceID": "a1b2c3d4e5",    "status": "pending",    "attempts": 10,    "responseCode": 10,    "mode": "live",    "createdAt": "2026-07-06T10:00:00.000Z",    "deliveredAt": "2026-07-06T10:00:00.000Z"  }}

Resend a webhook delivery

POST/webhooks/deliveries/{id}/resend
Scope: webhooks:write

Path parameters

idstringrequired
Request
curl -X POST "https://nestuge.com/api/v1/webhooks/deliveries/a1b2c3d4e5/resend" \  -H "x-nestuge-api: nk_live_your_key"
Response · 200
{  "status": "success",  "message": "OK",  "data": {    "id": "a1b2c3d4e5",    "endpointID": "a1b2c3d4e5",    "eventType": "transaction.succeeded",    "resourceType": "transaction",    "resourceID": "a1b2c3d4e5",    "status": "pending",    "attempts": 10,    "responseCode": 10,    "mode": "live",    "createdAt": "2026-07-06T10:00:00.000Z",    "deliveredAt": "2026-07-06T10:00:00.000Z"  }}

Start building on Nestuge

Every Nestuge account comes with scoped API keys and webhooks. Free to start; the MCP server needs Plus.

Get started for freeSee pricing
Nestuge

Monetize your expertise. Go from idea to income.

Need help?support@nestuge.com
© 2026 Nestuge Inc. All rights reserved.