Creem Setup

Creem is one of the two built-in payment adapters. The integration creates hosted checkouts, generates customer portal links, schedules subscription cancellation, and normalizes signed webhooks into the same billing events used by Stripe.

1. Create products

Create a Creem product for every subscription period and credit pack shown by your application. The default visible catalog requires:

CREEM_PRODUCT_STARTER_MONTHLY=prod_xxx
CREEM_PRODUCT_STARTER_ANNUAL=prod_xxx
CREEM_PRODUCT_PRO_MONTHLY=prod_xxx
CREEM_PRODUCT_PRO_ANNUAL=prod_xxx
CREEM_PRODUCT_CREDITS_SMALL=prod_xxx
CREEM_PRODUCT_CREDITS_MEDIUM=prod_xxx
CREEM_PRODUCT_CREDITS_LARGE=prod_xxx

Environment names for Enterprise and landing products are extension points, not proof that those products are ready to sell. Enterprise is not in the built-in plan catalog, and the example landing entitlements need custom fulfillment before checkout can be enabled.

2. Configure test mode

NEXT_PUBLIC_ENABLE_PAYMENTS=true
PAYMENTS_PROVIDER=creem

CREEM_API_KEY=creem_test_xxx
CREEM_API_BASE=https://test-api.creem.io
CREEM_WEBHOOK_SECRET=replace_with_the_endpoint_signing_secret
# CREEM_SIGNATURE_HEADER=X-Creem-Signature

CREEM_PRODUCT_STARTER_MONTHLY=prod_xxx
CREEM_PRODUCT_STARTER_ANNUAL=prod_xxx
CREEM_PRODUCT_PRO_MONTHLY=prod_xxx
CREEM_PRODUCT_PRO_ANNUAL=prod_xxx
CREEM_PRODUCT_CREDITS_SMALL=prod_xxx
CREEM_PRODUCT_CREDITS_MEDIUM=prod_xxx
CREEM_PRODUCT_CREDITS_LARGE=prod_xxx

CRON_SECRET=replace_with_a_strong_random_server_secret

The adapter infers the test API for a test key, but setting CREEM_API_BASE explicitly makes the intended environment easier to review. Use https://api.creem.io with production credentials and production product IDs.

Keep test keys, test product IDs, and the test endpoint signing secret together. Never expose CREEM_API_KEY, CREEM_WEBHOOK_SECRET, or CRON_SECRET to browser code.

3. Configure the webhook

Point the active Creem endpoint to:

https://your-domain.com/api/payments/webhook

The verifier accepts the standard Creem signature header and supports an override through CREEM_SIGNATURE_HEADER. It verifies an HMAC-SHA256 signature over the unmodified request body.

Enable the checkout, subscription lifecycle, and payment events used by your catalog. The adapter normalizes these event families:

• completed checkout events;
• subscription creation, update, activation, trial, paid, scheduled cancellation, past-due, unpaid, paused, deleted, canceled, terminated, or expired events;
• successful and failed invoice events.

Unknown signed event types are acknowledged without fulfillment. Verify the exact events produced by the Creem API version used by your account in test mode.

4. Checkout and return behavior

Use the provider-neutral endpoints:

POST /api/payments/checkout
Content-Type: application/json

{ "skuKey": "credits_small" }

POST /api/payments/subscription/checkout
Content-Type: application/json

{ "planKey": "starter", "period": "year" }

Checkout metadata contains the authenticated user, catalog context, SKU or plan, provider, and request ID. Subscription checkout reuses the server-generated idempotency key as the Creem request ID.

Creem may append signed checkout parameters to the success URL. The client sends those parameters to /api/payments/confirm. A missing or unverifiable return signature is treated as deferred rather than as a failed payment, and even a valid signature does not fulfill the purchase. The signed webhook remains authoritative.

Cancellation is scheduled rather than immediate. Billing Portal uses the Creem customer ID stored on the subscription. Both operations resolve the stored provider, not the provider currently selected for new checkout.

5. Verify in test mode

npm run preflight
npm run test:unit

The opt-in smoke test creates a real Creem test checkout but does not submit payment:

PAYMENT_PROVIDER_SANDBOX_E2E=true \
  E2E_TEST_EMAIL=<existing-test-user-email> \
  E2E_TEST_PASSWORD=<test-user-password> \
  PLAYWRIGHT_BASE_URL=https://<preview-or-test-origin> \
  npm run e2e -- tests/e2e/payment-provider-sandbox.spec.ts --project=chromium

For a local server, set PLAYWRIGHT_BASE_URL=http://localhost:3000. The test deliberately skips when either test credential is missing, so a green command is not enough: acceptance requires the summary to report 2 passed and 0 skipped.

Complete acceptance requires a public HTTPS deployment:

1. complete a Creem test payment;
2. confirm the signed webhook is accepted;
3. read the subscription or credit transaction from the database;
4. replay the delivery and confirm it is deduplicated;
5. verify portal creation and scheduled cancellation.

See Webhooks, subscriptions, and credits for the shared lifecycle contract.