Swell platform help — API-first headless SaaS commerce backend (swell.is, github.com/swellstores) with a native subscription engine: products, carts, orders, checkout, coupons/promotions, gift cards, B2B/wholesale, and custom data models via a REST Backend API (api.swell.store, secret-key auth, swell-node/PHP libs, port 8443) plus a Frontend API (swell-js + GraphQL at {store}.swell.store/graphql/v2) and Swell Apps functions. Use when building a Swell Backend or Frontend API integration, choosing public vs secret API keys, wiring a Swell webhook to a CRM or warehouse (events are IP-allowlisted, no HMAC), migrating active subscribers without double-billing (the $migrate:true footgun), checkout forcing a shipping address on a digital-only order, hitting a plan's monthly API-request limit, or comparing Swell pricing/subscriptions vs Shopify/BigCommerce/Medusa. Do NOT use for cross-cart checkout-conversion tactics (use /sales-checkout) or picking a Merchant of Record for global tax (use /sales-merchant-of-record).
Swell platform help — API-first headless SaaS commerce backend (swell.is, github.com/swellstores) with a native subscription engine: products, carts, orders, checkout, coupons/promotions, gift cards, B2B/wholesale, and custom data models via a REST Backend API (api.swell.store, secret-key auth, swell-node/PHP libs, port 8443) plus a Frontend API (swell-js + GraphQL at {store}.swell.store/graphql/v2) and Swell Apps functions. Use when building a Swell Backend or Frontend API integration, choosing public vs secret API keys, wiring a Swell webhook to a CRM or warehouse (events are IP-allowlisted, no HMAC), migrating active subscribers without double-billing (the $migrate:true footgun), checkout forcing a shipping address on a digital-only order, hitting a plan's monthly API-request limit, or comparing Swell pricing/subscriptions vs Shopify/BigCommerce/Medusa. Do NOT use for cross-cart checkout-conversion tactics (use /sales-checkout) or picking a Merchant of Record for global tax (use /sales-merchant-of-record).
argument-hint
[describe what you need help with in Swell — e.g. 'sync new orders to my CRM' or 'public vs secret API key']
license
MIT
version
1.0.0
tags
["sales","checkout","ecommerce","platform"]
github
https://github.com/swellstores
Swell Platform Help
Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
Figure out what the user actually needs before diving in:
Goal — building/debugging an API integration, reacting to a commerce event, a subscription/billing question, a checkout/conversion question, a migration, or a store-ops task?
Surface — Backend API (api.swell.store, secret key, server-side), Frontend API (swell-js or GraphQL, public key, client-side), webhooks, Swell Apps (serverless functions + custom models), the Swell CLI, or the dashboard UI?
Key type — a secret key (full backend access — server-only) vs a public key (storefront/read scope — safe in the browser)? Using the wrong one is the most common auth mistake.
Plan — Starter / Basic / Standard / Unlimited / Custom? Subscriptions, multi-currency, and API-request limits are plan-gated.
Skip-ahead rule: if the prompt already says what they need, go straight to Step 2.
Step 2 — Route or answer directly
If the question is really cross-platform strategy, hand off with the exact command:
If the user wants…
Route to
Checkout conversion / order bumps / cart-abandonment tactics across carts
/sales-checkout {question}
Choosing a recurring-billing engine across tools (Swell vs Recharge/Chargebee/Stripe Billing)
/sales-subscription-billing {question}
Whether to use a Merchant of Record for global VAT/sales tax
/sales-merchant-of-record {question}
Digital-product pricing & launch strategy
/sales-digital-products {question}
Comparing Swell against another commerce backend
/sales-checkout {question} (platform selection)
Otherwise it's a Swell-specific question — answer it here.
Step 3 — Swell platform reference
Read references/platform-guide.md for the full reference — capabilities and what's API vs webhook vs UI-only, pricing/plan gates, data model with JSON shapes, and quick-start recipes. For raw auth/endpoint/pagination/webhook detail, read .
references/swell-api-reference.md
Answer using only the relevant section — don't dump the whole guide.
Step 4 — Actionable guidance
You no longer need the full guide — focus on the user's situation.
Pick the key by where the code runs. Server-side (Node/PHP/scripts) → secret key + swell-node/swell-php against https://api.swell.store. Browser/storefront → public key + swell-js or GraphQL (https://{store}.swell.store/graphql/v2). Never ship a secret key to the client.
Official libraries need port 8443 open.swell-node/swell-php use a custom wire protocol on port 8443 for performance/caching — if a server can't reach it, fall back to plain REST over 443 or fix the egress firewall.
Webhooks are thin and unsigned. The payload carries model, type, and data (with the record id); there's no HMAC — secure the endpoint with the Swell IP allowlist + a secret URL/header, return 2xx within 10s, and look the full record up by id via the Backend API.
Never set $migrate: true when importing subscriptions. It skips the events that schedule billing — import them as normal records so billing anchors and next-charge dates are set correctly.
Mind plan gates. Subscriptions need Basic+, multi-currency/price-lists need Standard+, and every tier has a monthly API-request cap ($5 / 100K over) — check the plan before promising an integration.
If you discover a gotcha or fix not in references/learnings.md, append it there with today's date.
Gotchas
Best-effort from research (2026-06) — re-verify plan gates, fees, auth, port, and webhook signing against live docs.
Two API keys, two scopes. A secret key has full backend access and must stay server-side; a public key is for storefront/GraphQL and is browser-safe. Get both from Settings → API (store ID is shown there too).
Webhooks have no HMAC signature. Verify origin with the published Swell IP allowlist and a secret URL/path or custom header — don't assume a signing secret like Stripe/Shopify. Endpoints auto-disable after repeated failures (hourly retries ~2 days, warnings, then off ~day 3; auto_disabled after 7 days).
Digital-only carts still ask for shipping. Swell has historically forced shipping fields even on digital goods — set the product delivery to giftcard/subscription/none and handle the address requirement in your storefront logic.
No custom SMTP. Transactional email sends from Swell's infrastructure — you can't point it at your own SMTP; route critical mail through a webhook + your own ESP if you need full control.
API/docs maturity varies. Reviewers report rough edges and slow support on niche areas (some integration docs thin, content-model editor bugs). Prefer driving the store via the Backend API over the dashboard, and keep a fallback for undocumented behavior.
Subscription import = double-bill risk. See $migrate: true above — get a sandbox import right before touching live subscribers.
Related skills
/sales-checkout — Checkout-conversion strategy across carts (order bumps, upsells, cart-abandonment recovery) and platform selection; has an In Swell section.
/sales-subscription-billing — Choosing/operating a recurring-billing engine; compare Swell's native subscriptions vs Recharge/Chargebee/Stripe Billing.
/sales-bigcommerce — Another API-first SaaS commerce backend; the platform Swell most directly positions against.
/sales-merchant-of-record — Whether to use a MoR (Paddle, Lemon Squeezy) for global tax instead of self-managing (Swell is not a MoR).
/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: Sync new Swell orders into a CRM (developer/automation)
User: "I want my CRM to get a record every time someone places an order in Swell. I set up a webhook but the payload only has an id — where's the rest of the order?"
Approach: Explain Swell webhooks are thin — the POST body is {id, date_created, model:"order", type:"order.created", data:{id, ...}}, so use data.id to fetch the full order from the Backend API (swell.get('/orders/{id}') with the secret key, server-side). Configure the webhook at Developer → Webhooks (or via a Swell App) on the order.created event. Since there's no HMAC, restrict the endpoint to Swell's IP allowlist + a secret path/header, return 2xx within 10s (do the CRM write async), and remember the hook auto-disables after repeated non-2xx responses.
Example 2: Public vs secret key for a Next.js storefront (developer/automation)
User: "I'm building a headless storefront on Next.js. My product list works locally but I'm nervous I'm leaking a key. Which key goes where?"
Approach: Use the public key with swell-js (swell.init('<store-id>', '<public_key>')) or GraphQL (https://<store-id>.swell.store/graphql/v2, public key in the Authorization header) for anything that runs in the browser — product lists, cart, account session. Keep the secret key strictly in server code (route handlers / server actions) with swell-node against https://api.swell.store for admin reads/writes. If a secret key ever shipped to the client, revoke and rotate it in Settings → API.
Example 3: Migrating active subscribers without double-billing
User: "I'm moving ~400 active subscriptions into Swell from another tool. How do I import them so people aren't charged twice or skipped?"
Approach: Import each subscription as a normal record and do NOT pass $migrate: true — that flag suppresses the events Swell uses to schedule billing, which corrupts next-charge dates and anchors. Set the existing billing interval, the current period/anchor, and payment method, then verify the computed next charge date on a sandbox store before running it live. Reconcile against the old system's renewal dates, and watch the first billing cycle closely. (For the cross-platform billing-engine decision, route to /sales-subscription-billing.)
Troubleshooting
"My webhook fired but the payload doesn't contain the data I need"
Swell payloads are intentionally thin: {id, date_created, model, type, data} where data includes the record id and a subset of fields. Use data.id to GET the full record from the Backend API (e.g. swell.get('/orders/{id}')). Don't rely on the webhook body alone for full order/customer detail.
"My webhook keeps getting disabled"
Swell retries non-2xx deliveries hourly for ~2 days, then sends warning emails, then auto-disables the hook around day 3 (and auto_disabled trips after 7 days of failures). Make your handler return 2xx within the 10s timeout — acknowledge fast and process asynchronously — and confirm your endpoint accepts Swell's allowlisted IPs over HTTPS. Re-enable the hook in Developer → Webhooks once fixed.
"My official-library calls hang or time out"
swell-node and swell-php use a custom wire protocol on port 8443 (not 443). If your server/firewall blocks outbound 8443 the calls hang. Open egress to api.swell.store:8443, or use the plain REST/GraphQL HTTP interface over 443 instead. Also confirm you're using the secret key server-side (a public key will fail or return scoped/empty data on admin endpoints).
