Skip to content
keepcadence docs

Runbook: Polar (billing / payments)

Service overview

Section titled “Service overview”

Polar handles credit purchases and subscription management. The API integrates with Polar via @keepcadence/pricing. Webhooks from Polar update user_credit rows. Dev/staging uses the Polar sandbox org; production uses the production org.

Symptoms → Diagnosis → Fix

Section titled “Symptoms → Diagnosis → Fix”

Credit not added after successful payment

Section titled “Credit not added after successful payment”

Diagnosis

  1. Check polar_webhook_event (or equivalent audit table) for the Polar order event.
  2. Check API logs for webhook processing errors.
  3. Confirm the Polar webhook secret in Coolify env vars matches the one in Polar dashboard.

Fix

  • If webhook not received: re-trigger from Polar dashboard → Webhooks → Redeliver.
  • If webhook received but failed: check POLAR_API_KEY validity; keys expire or can be revoked.
  • Manual credit grant (emergency): bun --filter @keepcadence/api grant-credits -- --user <id> --amount <n>.

Subscription webhook returns 400

Section titled “Subscription webhook returns 400”

Diagnosis

  • Usually a signature mismatch — POLAR_WEBHOOK_SECRET env var is wrong or the webhook URL changed.

Fix

  • Re-generate the webhook secret in Polar dashboard and update Coolify env var.
  • Ensure the webhook URL points to https://api.keepcadence.com/webhooks/polar (prod) or staging equivalent.

Sandbox vs production mismatch

Section titled “Sandbox vs production mismatch”

Diagnosis

  • POLAR_API_BASE_URL / POLAR_WEB_BASE_URL are set to sandbox in prod, or vice versa.

Fix

  • Check APP_ENV; for prod, POLAR_API_BASE_URL must be https://api.polar.sh.
  • For dev/staging, use https://sandbox-api.polar.sh.

Contacts

Section titled “Contacts”