Plans & Pricing

Plans live in pricingConfig - a standalone named export from packages/config/src/pricing.ts, not a key on config. It holds plans: PricePlan[], a defaultPlan id, and optional credits/products blocks, and renders the landing page's pricing section even when config.payment.enabled is false.

Shipped plans

• Web upgrades and downgrades are ranked by price (per month, in the currency the subscription is billed in), never by array position: a switch of a running subscription applies at once (in the shipped UI after the customer confirms the amount in-app; the server also accepts a switch with no confirmed preview and charges it as of now - see Stripe plan changes) only when the new price is strictly higher per month (or equal at a longer interval), the interval is not shorter, and the prices Stripe actually bills agree (one licensed per-unit item at quantity 1, above zero, same currency). Everything else waits for the period end; if Stripe cannot be read the switch is refused (503) and can be retried. A subscription schedule created outside the app (Stripe dashboard) blocks in-app switches until you cancel it there. A switch that cannot be judged (another customer's subscription, a new price Stripe cannot bill in the subscription's currency) is refused. A new checkout is refused while the customer already holds a Stripe subscription that has not ended, so an account never runs two. App-store tiers still follow array position.
• The billing screen names a pending change - "Switching to Pro monthly on Dec 1", or the date a cancellation ends the subscription (pendingPlan / pendingChangeAt, with pendingUpgrade for an upgrade awaiting payment, on GET /billing/subscription/pending - read from Stripe, signed-in sessions only, and called by the billing screen alone so the frequently-polled GET /billing/status never spends Stripe's rate limit). A scheduled downgrade or a pending cancellation can be undone from the billing screen (web and desktop) with Keep my current plan (POST /billing/subscription/keep-plan, signed-in sessions only, the caller's own subscription only). It releases only schedules the app created; one made in the Stripe dashboard is left for you to change.
• defaultPlan ships "free" and is assigned to new users; null for no default.
• defaultApiRateLimit ({ maxRequests: 100 }) applies to any plan omitting apiRateLimit.
• trialDays sets the free trial (14 days on Starter, Pro and Business); add grantCreditsOnTrial to grant credits during it.
• Credit fields apply only when credits are enabled - see Credits.

PricePlan fields

Each entry in plans is a PricePlan (packages/config/src/types/index.ts).

PriceOption fields

A plan's prices array carries one PriceOption per billing interval.

Every currency code used in amounts must exist in config.currency.list, or it can be neither selected nor displayed.

A plan, annotated

The pro plan shows the full shape - two intervals, anchor pricing, one provider ref per price:

// packages/config/src/pricing.ts
{
  id: "pro",
  type: "subscription",
  name: "pricing.plans.plan_3.name",         // i18n key
  description: "pricing.plans.plan_3.description",
  featured: true,                            // recommended badge
  features: ["pricing.plans.plan_3.features.item_1", /* … */],
  prices: [
    {
      stripePriceId: "",                     // your provider's ref - fill from the dashboard
      interval: "month",
      amounts: { USD: 29 },
      anchorAmounts: { USD: 39 },            // strike-through
      featured: true,
    },
    { stripePriceId: "", interval: "year", amounts: { USD: 290 }, anchorAmounts: { USD: 349 } },
  ],
  credits: 50,                               // granted per cycle
  creditInterval: 30,                        // re-grant every 30 days
  apiRateLimit: { maxRequests: 5000 },
}

Selling by Stripe lookup key

Leave stripePriceId blank and set stripeLookupKey to sell each price by its Stripe lookup_key, so test and live mode each use their own price with no id committed.

prices: [
  { stripePriceId: "", stripeLookupKey: "pro_monthly", interval: "month", amounts: { USD: 29 } },
  { stripePriceId: "", stripeLookupKey: "pro_yearly", interval: "year", amounts: { USD: 290 } },
],

Currency

Display currency comes from config.currency in packages/config/src/index.ts.

• Add a currency by adding a Currency object to list, then its code to every amounts/anchorAmounts map that should support it.
• mainCurrency resolves the base currency object from list; countryMap.default covers unmapped visitors.
• Currency selection and rendering are framework-specific - see Data fetching and Theming.
• Changing base after launch means adding that code to every existing price. Historical revenue rows keep the currency they were recorded in.

Every price needs the base currency

base is the only mandatory currency. Every amounts map - plans, products, any anchorAmounts - must price config.currency.base. The rest of list is optional: a visitor whose currency is not priced sees the base price.

Revenue and refunds

Recorded revenue is net of sales tax on both providers - collected tax is owed to a tax authority, never income.

Refunds reverse what was recorded, not what the provider reports refunding. A refund takes its share of the revenue the purchase booked - 25% refunded reverses 25% - so a full refund nets to exactly zero and partial refunds reverse the whole and never more, on either provider's tax basis.