Pricing Configuration (config/pricing.ts)

Good to know

Since v4.0.0, pricing is no longer stored in the database and the admin dashboard no longer has a pricing management page. config/pricing.ts is the single source of truth for pricing.

Why pricing lives in code

• A price change is rare but high-stakes. It deserves a code review, not two clicks in an admin panel
• The payment provider is always the source of truth for money. This file does exactly one job: map a plan slug to "the provider-side price object + the credits it grants + its card copy"
• Card copy (name, description, feature list) is inlined on the plan object itself. One plan is one object, no longer scattered across i18n files

What a plan looks like

Subscription plan

{
  id: 'pro-monthly',            // Stable slug; orders and the credit ledger reference it forever
  kind: 'subscription',
  interval: 'month',            // 'month' | 'year'
  monthlyCredits: 2000,         // Credits granted per month (the subscription bucket RESETS to this)
  provider: 'stripe',           // Who collects the money
  stripePriceId: {              // Provider-side reference, one per environment
    test: 'price_xxx_test',
    live: 'price_xxx_live',
  },
  price: 29.9,                  // Display price in major units, not cents
  currency: 'USD',
  popular: true,                // Highlight this card on the pricing page
  active: true,
  copy: {
    en: { name: 'Pro', description: '...', features: ['2,000 credits every month', '...'] },
    zh: { name: '专业版', description: '...', features: ['每月 2,000 积分', '...'] },
    ja: { name: 'プロ',   description: '...', features: ['毎月 2,000 クレジット', '...'] },
  },
}

Credit pack (one-time purchase)

{
  id: 'pack-standard',
  kind: 'credit_pack',
  credits: 5000,                // Granted once into the purchased bucket; never expires
  provider: 'stripe',
  stripePriceId: { test: '...', live: '...' },
  price: 49,
  currency: 'USD',
  active: true,
  copy: { en: { ... }, zh: { ... }, ja: { ... } },
}

Team plan

{
  id: 'team-monthly',
  kind: 'subscription',
  interval: 'month',
  audience: 'team',             // Marks a team plan: the billing subject is an organization
  seats: 5,                     // Seat cap, enforced at invite and join
  monthlyCredits: 10000,        // Granted into the organization's shared pool
  provider: 'stripe',
  stripePriceId: { test: '...', live: '...' },
  price: 149.5,
  currency: 'USD',
  active: true,
  copy: {
    en: {
      name: 'Team',
      description: 'For teams that create together — one shared pool, five seats.',
      features: [
        // The object form with highlight elevates the whole row — team-only perks
        { text: '**10,000 credits** every month in a shared team pool', highlight: true },
        { text: '**5 seats** included — invite your whole team', highlight: true },
        'Everything in Pro, for every member',   // A plain string renders muted
      ],
    },
    // zh / ja follow the same shape
  },
}

Field reference

Shared fields

Subscription-only fields

Credit-pack-only fields

Filling in the provider reference

Each plan declares who collects the money with provider, then fills in only the matching field:

Every such field holds two values, { test, live }. Which one is used follows the environment:

• Stripe follows the STRIPE_SECRET_KEY prefix (sk_test / sk_live)
• PayPal follows NEXT_PUBLIC_PAYPAL_ENVIRONMENT (sandbox / live)

So the same config file runs unchanged in both test and production.

Creating the Stripe prices with a script

If you would rather not create each product by hand in the Stripe dashboard:

# Dry run — only prints what would be created
pnpm stripe:bootstrap
 
# Apply: create the Stripe products and prices, and backfill config/pricing.ts
pnpm stripe:bootstrap --write

The script is idempotent: products are reused by metadata.planId, prices are matched and reused by amount + currency + interval, and entries already backfilled are skipped. The column it writes follows the STRIPE_SECRET_KEY prefix.

Localized copy

copy is a { locale: PlanCopy } object; en is mandatory and backs every unknown locale:

interface PlanCopy {
  name: string
  description: string
  features: PlanFeature[]
}
 
type PlanFeature =
  | string                                  // Plain row, rendered muted
  | { text: string; highlight?: boolean }   // highlight: true elevates the whole row

Feature rows support **bold** segments. highlight: true is reserved by convention for team-exclusive perks (seats, the shared pool, per-member stats) so they pop against the shared baseline.

Read copy with getPlanCopy(plan, locale), which falls back to en for unknown locales.

Promotion codes

Two levels; the plan level beats the site level:

// Site-wide campaign
export const pricingCampaign: PricingCampaign = {
  promotionCode: 'LAUNCH20',
}
 
// A single plan
{ id: 'pro-monthly', promotionCode: 'PRO30', ... }

With a code configured, checkout applies it automatically (supported by Stripe and Creem; not by PayPal). Without one, the checkout page shows the provider's own manual promo-code input instead.

The codes themselves are created and managed on the Stripe side, and the boilerplate ships a coupon console. Note that test and live mode each need their own copy of the same customer-facing code.

Good to know

If the configured code does not exist or is inactive in the current mode, checkout does not fail — it falls back to the manual input. A stale campaign config never blocks a sale.

The iron rule about retiring a plan

A planId is never reused, and a plan entry that has ever been sold is never physically deleted.

Every renewal and upgrade invoice of an existing subscription resolves its plan through this file (both paths — metadata.planId and the provider-side price id — land here). Deleting an entry means:

1. Webhook fulfillment throws on every invoice → returns 5xx
2. Stripe retries with exponential backoff for up to 3 days
3. Every attempt mails the admin a grant-failure alert

Always retire with active: false. It only affects the pricing page; historical resolution keeps working.

Lookup helpers

config/pricing.ts also exports derived arrays and lookup functions — runtime code reads only these:

How the frontend renders it

The pricing page components live in components/pricing/:

• PricingSection.tsx — Server Component with the id="pricing" anchor. Three tabs (monthly / yearly / credit packs); when a team plan exists for that interval, a team sub-section is appended under the personal grid
• PricingCard.tsx — A single card. The CTA routes to PayPalCheckoutButton for PayPal credit packs and to CheckoutButton otherwise
• CheckoutButton.tsx — Calls createCheckoutSession and redirects to the provider checkout, mapping each guard code to the right destination (login page, billing page, team page, or a toast)

Section-level UI text (headings, tab labels) comes from the Pricing i18n namespace; plan copy comes from this file.

After changing pricing

1. Restart the dev server (the config is a module-level constant, so hot reload may not pick it up)
2. The pricing page, checkout and webhooks all read the new config — nothing else to sync
3. Before going live, make sure the live column of every price id is filled in