Lemon Squeezy Failover Runbook

Switch nSelf billing from Stripe to Lemon Squeezy in under 15 minutes. Existing Stripe subscriptions keep running — only new checkouts route through Lemon Squeezy.

When to use this

Stripe experiences a regional outage or checkout degradation
Stripe terminates the nSelf merchant account
EU VAT or US sales-tax compliance requires a Merchant of Record

Prerequisites

The following must be configured in ping_api environment variables before starting:

Variable	Where to find it
`LEMONSQUEEZY_API_KEY`	Lemon Squeezy dashboard → Settings → API Keys
`LEMONSQUEEZY_STORE_ID`	Dashboard URL: `app.lemonsqueezy.com/stores/{id}`
`LEMONSQUEEZY_WEBHOOK_SECRET`	Dashboard → Webhooks → your endpoint secret
`LEMONSQUEEZY_VARIANT_ID_*`	Dashboard → Products → each product → Variants

Verify the webhook endpoint is registered at:

https://ping.nself.org/webhooks/lemonsqueezy

with all subscription events enabled (subscription_created, subscription_updated, subscription_cancelled, order_created).

Step-by-step activation (~10 min)

1. Verify LS credentials (2 min)

source ~/.claude/vault.env
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $LEMONSQUEEZY_API_KEY" \
  https://api.lemonsqueezy.com/v1/stores/$LEMONSQUEEZY_STORE_ID
# Expected: 200

2. Health-check the admin endpoint (1 min)

curl -s -H "X-Admin-Key: $PING_API_ADMIN_KEY" \
  https://ping.nself.org/admin/payment-provider | jq .

Expected output:

{
  "active": "stripe",
  "persisted": "stripe",
  "stripe_configured": true,
  "lemonsqueezy_configured": true
}

If lemonsqueezy_configured is false, stop here — set the missing env vars and redeploy ping_api before continuing.

3. Switch the active provider (1 min)

curl -s -X POST \
  -H "X-Admin-Key: $PING_API_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"lemonsqueezy"}' \
  https://ping.nself.org/admin/payment-provider | jq .

Expected:

{
  "previous": "stripe",
  "active": "lemonsqueezy",
  "message": "Payment provider switched to lemonsqueezy. New checkouts will use lemonsqueezy. Existing subscriptions continue unaffected."
}

4. Verify the switch took effect (1 min)

curl -s -H "X-Admin-Key: $PING_API_ADMIN_KEY" \
  https://ping.nself.org/admin/payment-provider | jq .active
# Expected: "lemonsqueezy"

5. Test a checkout (5 min)

Open https://cloud.nself.org/pricing in a private window and start a checkout. Confirm the checkout page is hosted at checkout.lemonsqueezy.com rather than checkout.stripe.com.

If Stripe Elements appear instead of the LS checkout page, the cloud frontend is caching old provider state. Add a query param to bust the cache: ?_bust=$(date +%s).

6. Update status page (1 min)

Post to status.nself.org (or nSentry status page if live):

Billing: switched to backup payment provider. Existing subscriptions unaffected.

Coexistence during switchover

While PAYMENT_PROVIDER=lemonsqueezy:

New checkouts go through Lemon Squeezy
Existing Stripe subscriptions keep renewing — Stripe webhooks (/webhooks/stripe) continue processing renewals, cancellations, and payment failures
The /webhooks/lemonsqueezy endpoint handles new LS events in parallel
License activation works identically for both providers

There is no need to migrate existing Stripe subscribers to Lemon Squeezy. They stay on Stripe until they cancel; new sign-ups go through LS.

Reverting to Stripe

curl -s -X POST \
  -H "X-Admin-Key: $PING_API_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"stripe"}' \
  https://ping.nself.org/admin/payment-provider | jq .

Environment variable alias

The internal switch uses PAYMENT_PROVIDER. The admin panel and cloud frontend also read BILLING_PROVIDER as an alias for display purposes — set either one. The factory in payments/factory.ts reads PAYMENT_PROVIDER as the authoritative source; BILLING_PROVIDER is surfaced in health checks only.

Troubleshooting

Symptom	Check
`lemonsqueezy_configured: false`	Missing one of the three required LS env vars
Checkout still goes to Stripe	Vercel may be caching a CDN response — check `PAYMENT_PROVIDER` in Vercel env
Webhook signature failures	`LEMONSQUEEZY_WEBHOOK_SECRET` mismatch — regenerate in LS dashboard and redeploy
License not activated after purchase	Check `np_payment_events` for the LS event ID; check ping_api logs
`503 Lemon Squeezy not fully configured`	One of the three required vars is missing from the running ping_api process