Shipflash logoDocs

Choose Your Product Edition

Select one isolated billing provider edition first, then configure the modules and commercial models your SaaS actually needs.

On this page

Provider editions

The names below describe the delivered branch and the public integration surface. Select one edition; the application does not run all five billing providers together.

ProviderBuilder referenceSupported modelsCatalog keyWebhook route
Stripe
Implementation referencesupabase/stripe
All five billing modelsstripePriceId/api/webhooks/stripe/billing
Lemon Squeezy
Implementation referencesupabase/lemonsqueezy
All five billing modelslemonsqueezyVariantId/api/webhooks/lemonsqueezy
Dodo Payments
Implementation referencesupabase/dodo
All five billing modelsdodoProductId/api/webhooks/dodo
Polar
Implementation referencesupabase/polar
All five billing modelspolarProductId/api/webhooks/polar
Creem
Implementation referencesupabase/creem
Recurring, one-time, and prepaid creditscreemProductId/api/webhooks/creem

Configure the selected edition

  1. 1

    Confirm the provider lock

    After cloning or pulling the selected edition, verify the branch and read the provider-specific environment section before adding credentials. Do not change BILLING_PROVIDER to another provider in a buyer checkout.

    text
    git branch --show-current
git status --short
  2. 2

    Choose billing models

    Select only the commercial models your product will sell: licensed_recurring, licensed_one_time, metered_usage, prepaid_credits, and/or base_plus_usage. Creem supports licensed recurring, licensed one-time, and prepaid credits only.

    • Keep the catalog, model list, and provider product types aligned
    • Do not enable a model that the selected provider cannot fulfill
    • Treat credits as an app-local ledger, not a provider wallet
  3. 3

    Review the generated plan

    Run the plan and validation commands from Before You Customize. Read the module dependencies, files to remove or restore, package changes, and retained migrations before applying.

    text
    pnpm product:configure --plan
pnpm product:configure --validate
  4. 4

    Apply from a clean worktree

    Apply the approved selection, inspect the diff, and keep product.lock.json and the generated selection together in the same commit. If the plan is wrong, restore the pinned module instead of copying code from another provider branch.

    text
    pnpm product:configure --apply
git diff --check
git status --short
Implementation reference3 areas

These Product code locations explain how the documented behavior is implemented. Expand them when you are ready to customize or maintain this area.

Delivered provider lock

The distribution metadata and selected adapter composition establish which provider the checkout can run.

  • src/config/product-distribution.ts
  • src/features/billing/server/providers/runtime/selected.ts
  • src/features/billing/server/runtime/provider.ts

Billing model and catalog policy

The runtime validates enabled models and provider-compatible catalog identifiers before checkout.

  • src/features/billing/server/runtime/enabled-models.ts
  • src/features/billing/server/catalog/configuration.ts
  • src/features/billing/shared/catalog/schemas.ts

Webhook and worker boundary

The selected webhook boundary verifies and stores provider events; the application worker performs projection with retry and dead-letter handling.

  • src/app/api/cron/billing-webhooks/route.ts
  • src/features/billing/server/webhooks/worker.ts
  • src/app/api/webhooks/dodo/route.ts
  • src/app/api/webhooks/polar/route.ts
  • src/app/api/webhooks/creem/route.ts

Reference paths are relative to the delivered product checkout.

Edition selection is complete when

  • The local branch matches the provider you intend to operate.
  • Only supported billing models are enabled.
  • The catalog uses real IDs from the same provider environment and mode.
  • The plan was reviewed before apply and product.lock.json is committed.
  • The selected webhook route and billing worker have a documented schedule.
  • Provider test mode, duplicate delivery, portal, refund, and entitlement projection are verified before live mode.