Pricing Page skill for Codex

A pricing page is done well when a visitor can identify their plan in under ten seconds, the price they see is the price they are charged (currency, tax, billing period), the comparison table answers “what do I lose by choosing the cheaper plan”, and every number comes from the same source as billing.

This skill covers packaging and the page. Choosing price levels and running willingness-to-pay research belongs to pricing-strategy.

Inspect first

1. Find where prices live today: rg -n "price_|priceId|lookup_key|monthly|annual|per seat|/mo" src/ app/ config/ -g '!node_modules'. Hard-coded numbers in JSX next to Stripe or Paddle price IDs in config are a mismatch waiting to happen.
2. Read the billing setup (Stripe Products and Prices, Paddle, Lemon Squeezy, Chargebee): which plans, intervals, currencies and tax behaviour exist.
3. Read AGENTS.md and the existing design system components for cards, tables, toggles.
4. Collect evidence: sales and support questions about pricing, plan distribution of current customers, upgrade triggers, churn reasons mentioning price.

Packaging decisions

Decision	Default	Change when
Number of tiers	3 self-serve (plus Enterprise)	One clear persona: 1-2 tiers; very broad market: add a free tier
Tier anchor	Middle tier as “Most popular”, sized for the core persona	Data shows most buyers choose a different tier
Value metric	Grows with value received (seats, usage, contacts, projects)	Metric customers cannot predict creates anxiety: offer bundles or caps
Free option	Free plan for products with viral/collaborative loops; trial otherwise	Support cost of free users is high: time-limited trial
Annual discount	~15-20% (“2 months free”)	Cash flow not a priority, or monthly churn is low
Enterprise	“Contact sales” tier with SSO, audit logs, SLA, invoicing, security review	Product has no enterprise buyer yet: omit it

Tier differentiation rules:

• Each tier is named for who it is for or how they work (“Solo”, “Team”, “Business”), not gemstones.
• Gate on features that matter more as customers grow (permissions, SSO, audit logs, API limits, integrations, support SLA), not on core value; crippling the base product kills conversion.
• Each tier has a one-line “for <persona> who need <thing>” description.
• Show what is in a tier as “Everything in Team, plus:” to keep cards short.

Page structure

1. Headline that states the deal plainly (“Simple pricing, free for small teams”).
2. Billing toggle (Monthly / Annual, savings shown as a concrete amount or “2 months free”); default to annual only if most customers choose it, and say “billed annually” next to the per-month figure.
3. Plan cards: name, persona line, price with unit ($12 per user / month), billing note, primary CTA, 4-6 key inclusions. One highlighted plan.
4. Logos or short social proof near the cards.
5. Comparison table: every feature grouped by category, sticky header with plan names and CTAs, tooltips for jargon. Use text (“Unlimited”, “3 projects”, ”-”) not just ticks.
6. Usage calculator if pricing depends on volume.
7. FAQ: billing cycle, upgrades and downgrades (proration), cancellation, refunds, taxes and VAT, payment methods, invoices/POs, discounts (education, nonprofit, startup), data on downgrade, what happens at limits.
8. Final CTA and contact-sales path.

Single source of truth

Generate both the page and the checkout from one config, or read prices from the billing provider at build time.

// pricing.config.ts - the only place prices and limits are written
export const plans = [
  {
    id: "team",
    name: "Team",
    persona: "For growing teams that ship together",
    prices: {
      month: { amount: 1500, currency: "usd", lookupKey: "team_monthly_usd" },
      year:  { amount: 14400, currency: "usd", lookupKey: "team_yearly_usd" },
    },
    unit: "per user",
    limits: { projects: Infinity, guests: 10 },
    highlights: ["Unlimited projects", "10 guest seats", "Priority email support"],
  },
] as const;

export const formatPrice = (cents: number, currency: string, locale = "en-US") =>
  new Intl.NumberFormat(locale, { style: "currency", currency, maximumFractionDigits: cents % 100 ? 2 : 0 })
    .format(cents / 100);

Then add a test that each lookupKey exists in the billing provider with the same amount (in CI with test-mode keys, or a script the user runs with network access). Stripe lookup keys let the code reference a stable key while the underlying Price changes.

Currency, tax and region

• Show local currency where you actually charge it; do not convert on the fly to a currency checkout will not use.
• US convention: prices shown excluding sales tax. EU/UK consumers expect VAT-inclusive prices; for B2C there, show inclusive prices or state clearly that VAT is added. Get the user’s accountant or tax provider (Stripe Tax, Paddle as merchant of record) to confirm the rule for each market.
• Annual price shown per month must state the billed annual total somewhere visible.

Structured data and SEO

• Pricing pages rank for ”<brand> pricing”; give the page a clear title and meta description that include the starting price if it is stable.
• Product or SoftwareApplication JSON-LD with offers is optional; if used, prices must match the visible page exactly. Details belong to schema-markup.

Honesty rules

• No fake strike-through “was” prices; reference prices must be real prices actually charged.
• No pre-checked add-ons, no hidden fees revealed only at checkout.
• Cancellation should be as easy as signup; US state automatic-renewal laws (California’s among the strictest), the federal ROSCA statute and EU consumer rules require clear renewal terms and simple cancellation. Describe the real process in the FAQ.
• “Free” means free: state limits and what happens when they are reached.

Changing live prices

Changing prices or plans on the live site and in billing affects real customers and revenue. Prepare the config change, page and a migration note for existing customers (grandfathering, notice period), and ship only after the user confirms. Never edit live Prices in the billing provider from Codex without explicit approval.

Gotchas

• Page says “$15/user”, checkout charges $18 because a new Price was created in Stripe and the page was not updated. Single config plus a test prevents it.
• Annual toggle shows per-month price without “billed annually”; leads to refund requests.
• Comparison table with 60 rows of ticks nobody can scan; group and cut to what differs.
• “Contact sales” as the only path for mid-market buyers who want to self-serve.
• Mobile: comparison tables overflow; use per-plan accordions or a sticky plan selector.

Verification

• Every displayed price equals the billing provider’s amount for that lookup key and currency (automated check).
• Click each CTA through to checkout in test mode; plan, interval and currency are preselected correctly.
• Five-person or five-question test: “Which plan would you pick and what will you pay per year?” answered correctly from the page alone.
• Page renders at 375 px without horizontal scroll; toggle and table are keyboard accessible.

Output template

## Pricing page: <product>
**Tiers:** table (name, persona, price month/year, value metric, key gates)
**Changes from current:** ...
**Source of truth:** pricing.config.ts <-> billing lookup keys (check: passing)
**Sections:** headline, toggle, cards, comparison, FAQ (questions listed)
**Regional/tax display:** ...
**Open questions for user:** price levels (pricing-strategy), legal/tax review, grandfathering