Pricing & Coupons

A plan is the product definition your users buy. Providers fulfill the payment, but the app decides what a plan means: duration, token grant, renewal behavior, and whether it supports organizations.

The app uses two checkout shapes depending on what the user is buying:

Users encounter these flows primarily through /pricing, /dashboard/plan, and /dashboard/billing.

One-time purchases are more nuanced than “create a temporary plan.” The payment service resolves different behaviors depending on the user's current active subscription.

Lifetime one-time plans use the same flow shape with an explicit lifetime flag, so the branching stays minimal: the subscription is still created or extended through the normal one-time handlers, but the resulting access is treated as lifetime instead of finite-duration.

SaaSyBase supports per-provider, per-currency pricing through the PlanPrice model. A single plan can therefore have multiple localized prices without becoming multiple products in your app.

PlanPrice {
  planId
  provider
  currency
  amountCents
  externalPriceId
}

Example: the same plan can be $10 USD on Stripe and ₦15,000 NGN on Paystack without splitting your business logic into separate plans.

Recurring plans use both a unit and a multiplier:

Proration only applies when moving between recurring plans. It is not used for one-time purchases.

When PAYMENT_AUTO_CREATE="true", the app can create missing provider-side catalog objects for supported providers during seed or plan save flows.

PAYMENT_AUTO_CREATE="true"

In the admin plan UI, manual provider price ID fields are advanced overrides. The normal workflow is to leave them blank and let sync populate them.

Cancellation is generally handled as cancel-at-period-end rather than immediate loss of access.

Provider behavior differs. Stripe supports a native customer portal directly. Paystack relies on an app-level workaround. Some providers rely more on hosted management URLs than a full Stripe-style portal.

Coupons are provider-aware but app-controlled. SaaSyBase supports both native provider coupons and in-app discount calculation.

Admins manage the catalog from /admin/plans. The UI exposes both recurring and non-recurring offers, active subscriber counts, and sync helpers for provider price IDs.

Subscription lifecycle tools also exist in admin APIs, including schedule-cancel, expire, edit, and force-cancel flows. Those are documented in the API reference but matter here because they shape what billing management means operationally.

SaaSyBase generates provider-agnostic PDF invoices and refund receipts server-side using pdf-lib. That gives every provider a consistent document experience.