Documentation
Quick Start
Get a Serial Subscriptions instance running in minutes using the provided temporary domain alias.
1. Create your account and instance
- Sign up at serialsubscriptions.com and verify your email.
- Create an organization when prompted after first login.
- Create a project from the Projects page → New project:
- Enter a project name.
- Skip Use my own domain — the platform assigns a domain alias automatically.
- Choose Add default “Development” subscription plan (no credit card required).
- Select Create project, then Choose Development Plan on the next screen.
Wait for Status to finish provisioning. You will receive an email with a sign-in link to your new instance.
For more details, see Create a project.
2. Configure platform settings
Sign in to your new instance (you are the platform_admin) and open Platform Settings → Platform Setup Checklist. Work down the list; each row has a Modify button.
- Platform Settings — set the Site name.
- Theme Settings (optional) — logo URL, brand CSS URL, and font choices.
- Stripe Settings — pick Test or Live, paste your publishable and secret keys, then create a webhook endpoint in Stripe pointed at the Webhook Endpoint URL shown on the form. Enable all
payment_intent.*andpayment_method.*events and paste the signing secret as Webhook secret.
For full detail on every field, see Platform settings.
3. Pick a path
A) Deploy the demo app (AI Creator)
A ready-to-deploy Next.js example that exercises tiered plans, AI token metering, custom usage tracking, and limits.
- Sign in to the integration portal and open your project’s dashboard (Projects → your project → Integrate).
- Under Integrations, expand Demo App: AI Creator.
- Provision the secrets you’ll need:
- PostgreSQL connection string →
DATABASE_URL - Redis connection URL →
SSI_STORAGE_URL - OpenAI API key →
OPENAI_API_KEY
- PostgreSQL connection string →
- Click Set SSI_CLIENT_SECRET on the dashboard. This opens Auth Settings on your instance — click Generate, copy the value, and Save. Use that value as
SSI_CLIENT_SECRETin your deployment. - Click Deploy to Vercel. The portal prefills public env vars (
SSI_ISSUER_BASE_URL,SSI_COOKIE_DOMAIN,SSI_STORAGE_CONTAINER,SSI_STORAGE_BACKEND,SSI_CLIENT_ID); paste in your secrets from steps 3–4 and deploy. - Run the demo’s database migrations (command documented in the ai-creator-demo repo).
- On the dashboard, Copy the subscription-plan-template.json and import it via your instance’s Import page to load the tiered starter plans.
For full detail, see Deploy the demo app.
B) Deploy your own app
In your app’s repository, install the Serial Subscriptions skills bundle so your AI editor has the integration guides and snippets on hand:
npx skills add serialsubscriptions/skills
Then give your AI editor the following prompt:
Integrate Serial Subscriptions with my app. Every page should be gated. Read-only roles can have readonly access and write roles can have write access. We’ll define admin/owner permissions separately later. Organization is required for every route.
The skill walks the editor through installing @serialsubscriptions/platform-integration, wiring createSSI(), adding the auth route handlers, and applying requireAuth() with sessionRoles checks. Use the SSI_CLIENT_ID / SSI_CLIENT_SECRET / SSI_REDIRECT_URI / SSI_ISSUER_BASE_URL values from your Auth Settings (see step 4) when configuring the app’s environment.
4. Verify OAuth alignment
The deployed app and your instance’s Auth Settings must agree exactly. Open Platform Setup Checklist → OAuth App Integration → Modify and confirm:
| Auth Settings field | App env var | Notes |
|---|---|---|
| Client ID | SSI_CLIENT_ID | Byte-for-byte match. |
| New client secret (after Save) | SSI_CLIENT_SECRET | Generate, copy once, store only in deployment secrets. |
| Redirect URIs (one per line) | SSI_REDIRECT_URI | Use https://<your-app-host>/api/v1/auth/callback; must match exactly (scheme, host, path, no stray trailing slash). |
| (your instance’s HTTPS origin) | SSI_ISSUER_BASE_URL | The base URL of the Serial Subscriptions site itself — no path, no trailing slash. |
Recommended defaults on the Auth Settings form:
- Grant types — enable both Authorization code and Refresh token.
- Scope selection — All scopes (recommended).
- Additional OAuth Settings — Confidential client on, Require PKCE off, Automatic authorization on, Remember approvals on. Leave token expirations at defaults.
Then on Application Settings, set Login redirect URL and Logout URL to your app’s /api/v1/auth/login and /api/v1/auth/logout routes (these are different from the Redirect URIs callback above).
After deploy, hit Login, complete the flow, and confirm you land back on the app without an ?error= query string. See OAuth settings for the full walkthrough and troubleshooting.
Next steps
- Configure branding and Stripe in Platform settings.
- Wire up the
@serialsubscriptions/platform-integrationlibrary in your own Next.js / Node.js code. - Add a custom domain later under project settings (see the Verify your custom domain section of Create a project).