Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
-
What are you trying to do?
- A) Manage members from your backend (create/read/update/delete) via the Admin REST API
- B) Verify a member's JWT to gate your own API or app
- C) React to events via webhooks (member.created, member.plan.*) — sync to a CRM/warehouse
- D) Configure front-end auth, gating, or Stripe checkout (DOM package + data attributes)
- E) Pick a plan / understand transaction fees
- F) Fix a problem — webhook verification, json overwrite, member-not-found, 1.0→2.0 migration
-
Front-end or back-end? Browser auth/gating/checkout = DOM package (public key). Server-side member ops + token/webhook verification = Admin REST/Node (secret key). This decides everything.
Skip-ahead rule: if the user's prompt already provides enough context, skip to Step 2.
Step 2 — Route or answer directly
| If the question is about... | Route to... |
|---|---|
| Choosing or comparing membership/course platforms | /sales-membership {question} |
| Checkout-conversion / order-bump / upsell strategy across tools | /sales-checkout {question} |
| Email sequences and broadcasts (Memberstack doesn't send email) | /sales-email-marketing {question} |
| Wiring Memberstack into a CRM/warehouse or other tools | /sales-integration {question} |
| Membership/community structure, pricing, and retention strategy | /sales-membership {question} |
When routing, give the exact command, e.g. "Platform comparison — run: /sales-membership Memberstack vs a hosted course platform".
Step 3 — Memberstack platform reference
Read references/platform-guide.md for the full reference — the module map (DOM vs Admin, what's front-end vs server-side vs webhook), the plan/transaction-fee gates, the member data model with JSON shapes, and quick-start recipes (create a member server-side; verify a member JWT to gate your API; sync member.created to a CRM via webhook).
Read references/memberstack-api-reference.md for the Admin REST API — base https://admin.memberstack.com, X-API-KEY auth (sk_sb_ test / sk_live_ live, server-side only), the member CRUD + verify-token + add/remove-plan endpoints, cursor pagination, the 25 req/s limit, the 8 webhook events, and the webhook-signature-verification caveat.
Answer the user's question using only the relevant section. Don't dump the full reference.
Step 4 — Actionable guidance
Focus on the user's specific situation:
- Two packages, two keys. Front-end DOM package uses a public key (login/signup/gating/Stripe checkout in the browser); the Admin REST/Node package uses a secret key (server-side member ops). Never put a secret key client-side.
- Verify member JWTs to protect your own backend.
POST /members/verify-tokenturns a logged-in Memberstack session into a trusted member ID for your API. - Webhook signatures need the Node package. REST can't verify them — if you're REST-only, re-fetch the member by ID to confirm an event before trusting it.
- Watch the
jsonPATCH trap.customFields/metaDatashallow-merge, butjsonis fully replaced — read-modify-write to avoid wiping it. - Handle member-not-found as 200 + data:null, not 404.
- Respect 25 req/s — back off on 429; paginate lists with
after/endCursor(max 100). - Fees stack on Stripe. 0.9–4% by tier; only the $399 Established plan is 0% — run the math before pricing memberships.
If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.
Gotchas
Best-effort from research (2026-06) — review these, especially plan-gated features and pricing, which change frequently.
- Webhook signature verification is NOT supported via REST. Use the Node Admin package, or verify events out-of-band (re-fetch the member). Don't trust raw webhook payloads on a REST-only stack.
jsonis fully replaced on PATCH (whilecustomFields/metaDatashallow-merge). Read-modify-write thejsonobject or you'll silently wipe data.- Secret keys are server-side only. The DOM package's public key is fine in the browser; an
sk_*key in client code or a public repo is a breach. - Transaction fees stack on Stripe. 4% (Basic) / 2% (Pro) / 0.9% (Business) / 0% (Established $399) — plus Stripe's own fees. Only the top tier is fee-free.
- No permanently free live tier. Free until launch; the test key (
sk_sb_) caps at 50 test members. - Member-not-found returns 200 with
data: null, not 404 — handle it explicitly. - It's a layer, not a host. No course/LMS hosting, no marketing email — pair with an LMS and an ESP if you need those.
- 1.0 vs 2.0. 2.0 is the current rebuild with this API; 1.0 is legacy with a different API. Confirm which you're on.
Related skills
/sales-membership— Membership/course platform strategy, pricing, and retention, and choosing Memberstack vs a hosted course platform/sales-memberful— Memberful (the closest membership-first alternative: own-your-audience subscriptions, private podcasts/newsletters, GraphQL API + signed webhooks + OAuth, on your own Stripe)/sales-checkout— Checkout, subscription, and upsell optimization (Memberstack runs payments through Stripe)/sales-integration— Wiring Memberstack's API/webhooks into a CRM, warehouse, or other tools/sales-email-marketing— Email sequences for members (Memberstack doesn't send email — connect an ESP)/sales-do— Not sure which skill to use? The router matches any sales objective to the right skill. Install:npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: Create a member from my backend after an external signup (developer/automation)
User says: "When someone signs up through my own form, how do I create them in Memberstack from my server?"
Skill does: Shows POST https://admin.memberstack.com/members with the X-API-KEY secret key (server-side only), sending email + password (+ customFields) — Recipe 1 in references/platform-guide.md. Notes the 25 req/s limit, that the response returns a mem_* id, and that paid plans go through Stripe checkout on the front-end while free plans use the add-plan endpoint.
Result: User creates members server-side and understands key safety + the free-vs-paid-plan split.
Example 2: Gate my own backend API to logged-in members
User says: "My Webflow front-end uses Memberstack. How do I protect my custom API so only logged-in members can call it?"
Skill does: Points to POST /members/verify-token (Recipe 2) — the front-end sends the member's Memberstack JWT to your backend, which verifies it via the Admin API and gets the member ID before serving data. Explains the public-key (browser) vs secret-key (server) split.
Result: User validates Memberstack sessions server-side to authorize API calls.
Example 3: My webhook fires but I can't verify it / my json data got wiped
User says: "I'm syncing member.created to my CRM but can't verify the signature, and a PATCH erased my custom json."
Skill does: Explains webhook signature verification isn't supported via REST — use the Node package or re-fetch the member by ID to confirm (Recipe 3 + Gotcha 1). For the data loss, explains json is fully replaced on PATCH (unlike customFields/metaData) and to read-modify-write it (Gotcha 2).
Result: User hardens webhook trust and stops overwriting json.
Troubleshooting
I can't verify my webhook signatures
Symptom: No way to validate that a webhook POST really came from Memberstack via the REST API.
Cause: Webhook signature verification is only implemented in the Node.js Admin Package, not the REST API.
Solution: Use the Node Admin package for verification, or on a REST-only stack verify out-of-band — treat the payload as a hint and re-fetch the member with GET /members/:id before acting. Lock your webhook endpoint to a secret path and validate the member exists.
A PATCH wiped my member's custom data
Symptom: Updating a member erased fields you didn't send.
Cause: On PATCH /members/:id, customFields and metaData are shallow-merged, but json is fully replaced.
Solution: For json, read the current value first, merge your changes in app code, then send the complete object. Use customFields/metaData when you want partial updates.
Looking up a member returns nothing but no error
Symptom: GET /members/:id_or_email returns 200 and you expected a 404 for a missing member.
Cause: Memberstack returns 200 with "data": null for a non-existent member.
Solution: Check data === null rather than relying on the status code. URL-encode emails when looking up by email.
Hitting 429 / sync is throttled
Symptom: Bulk member operations start returning 429.
Cause: You've exceeded the 25 requests/second limit.
Solution: Throttle to ≤25 req/s, add exponential backoff on 429, and paginate reads with after + endCursor (max 100 per page) instead of hammering the list endpoint.