Pricing Updates & Stripe Runbook
How to change what PPP charges customers — end to end, from editing a constant to verifying a real Stripe charge in UAT and Prod.
TL;DR
PPP does not use Stripe Products or Prices. The backend sends a raw amount (in cents/pence) to stripe.paymentIntents.create() on every signup. To change a price you edit one TypeScript constant — no Stripe dashboard work needed. Every downstream surface (marketing site, tests, docs) reads from the same source of truth.
Current prices
Single source of truth
This table and packages-shared/ppp/src/constants/pricing.ts are the only places the literal AUD/GBP figures live. Every other doc links here instead of repeating the numbers, so there is nothing to drift. If you change a price, update this table and the constant — see §3 Step-by-step.
| Plan | Account type | AUD (incl. GST) | GBP (ex-VAT) |
|---|---|---|---|
| CPD Home | cpd | A$299 / year | £159 / year |
| PPP Full Platform | cpdppp | A$1,699 / year | £549 / year |
Both plans are billed annually as a single Stripe PaymentIntent (no recurring subscription). Tax collection is tracked in #5140; until that lands, the charged amount equals the displayed minor-unit value.
1. How PPP charges customers today
PPP uses Stripe PaymentIntents for one-shot annual charges. Every time a doctor clicks "Pay" in the signup flow, the backend does roughly this:
const amount = getAmountForCurrency(input.accountType, selectedCurrency);
// → 29900 (AUD cents for CPD) or 169900 (AUD cents for PPP Full)
await stripe.paymentIntents.create({
amount,
currency, // 'aud' or 'gbp'
payment_method_types: ['card'],
metadata: { accountType, userEmail, ... },
});The amount comes directly from PLAN_PRICES in packages-shared/ppp/src/constants/pricing.ts via getAmountForCurrency(). There is no Stripe Product, Price, Subscription, or Checkout Session involved. Stripe holds no record of "this is the $299 CPD plan" — it only sees a stream of one-off charges and whatever amount the backend happens to send.
Why this matters
| Stripe concept | Used by PPP today? | Why / why not |
|---|---|---|
| Products | ❌ No | PPP has no catalog in Stripe's dashboard |
Prices (price_… IDs) | ❌ No | Amounts are computed in backend code per request |
| Subscriptions | ❌ No | Annual billing is implemented as a one-shot PaymentIntent + DB-tracked expiry; customers re-pay annually |
| Checkout Sessions | ❌ No | The frontend uses Stripe Elements + confirmCardPayment() directly |
| PaymentIntents | ✅ Yes | One per signup; explicit amount in cents/pence |
| Webhooks | ✅ Yes | payment_intent.succeeded, payment_intent.payment_failed, payment_intent.canceled, and charge.refunded update the user's paymentStatus (and accountAccess on refund) |
If/when PPP migrates to Stripe Subscriptions or Checkout in the future, a Price object per plan per currency will become mandatory and this runbook will need to grow an "Update Stripe Price objects" step. Until then, the dashboard stays empty of catalog data.
2. Canonical source of truth
One file, two integers per plan per currency:
packages-shared/ppp/src/constants/pricing.ts
export const PLAN_PRICES = {
cpd: {
AUD: { annual: 29900 }, // A$299.00 incl. GST
GBP: { annual: 15900 }, // £159.00
},
cpdppp: {
AUD: { annual: 169900 }, // A$1,699.00 incl. GST — updated 2026-08-20
GBP: { annual: 54900 }, // £549.00
},
} as const;Everything else in the codebase — backend payment service, frontend signup, Billing page, marketing pricing cards, Guide content, legal docs, tests, BDD scenarios — either reads from this constant directly or references the same integer literals. When you change a price here, you need to fan out the same change to every hard-coded reference.
3. Step-by-step: change a plan price
3.1 Decide the new prices
Pick the new annual amount in minor units (cents for AUD, pence for GBP):
- $299.00 AUD =
29900 - £159.00 GBP =
15900
3.2 Edit the canonical constant
Update the relevant entry in packages-shared/ppp/src/constants/pricing.ts. Also update the JSDoc examples above formatPrice and getPriceLabel so they continue to match reality.
3.3 Fan out to hard-coded references
Run a repo-wide search for the old amount and replace it everywhere it legitimately refers to that plan:
# Find both forms (integer in code, display string in copy)
rg -n '\b19900\b|\$199\b|£99\b|\b9900\b' --type ts --type tsx --type md --type htmlReview each hit carefully — numeric substrings can collide (e.g. 9900 appears inside 1699900000, a Unix timestamp). Update only the ones that are actually prices.
Typical surfaces that need updating when CPD or PPP Full changes:
| Area | Path | What to change |
|---|---|---|
| Backend tests | api/backend-ppp/src/services/paymentService/** | All amount: N / paymentAmount: N / .toBe(N) in PaymentIntent assertions |
| Backend fixtures | api/backend-ppp/src/__fixtures__/responses/stripe.ts | Fixture amounts for MSW contract tests |
| Backend contract tests | api/backend-ppp/src/routers/procedures/payments/contracts.test.ts | PAYMENT_CONFIG.amounts.* assertions |
| Frontend Billing tests | instances/ppp/src/modules/Billing/Billing.test.tsx | formatCurrency assertions and payment history fixtures |
| Frontend Signup tests/stories | instances/ppp/src/modules/Signup/** | Mock PAYMENT_CONFIG.amounts, "Pay $N" button assertions |
| Marketing site | instances/marketing/src/landing/pages/Home.tsx | PlanCard price="$N" |
| Marketing legal | instances/marketing/src/landing/pages/{EULA,TermsOfService,SubscriptionRefundPolicy}/index.tsx | Plan tables in ToS, Refund Policy, EULA |
| Guide content | instances/ppp/src/modules/Guide/content/{fees-and-billing,plans-and-pricing}.md | Both AUD and GBP <!-- currency:... --> blocks |
| Docs | CLAUDE.md, docs/brand-guidelines.md, docs/ppp-infrastructure.md, docs/site/integrations/stripe.md | Any mention of the price in narrative copy |
| Brand kit | brand-kit/index.html | "From $N AUD/year" conversion copy |
| Mermaid journeys | docs-github/diagrams/journey-cpd-home.mmd | Select CPD Home plan\nAUD $N/yr label |
3.4 Add or update a BDD regression scenario
Per the BDD-first rule in CLAUDE.md, any change that touches instances/ppp/ or api/backend-ppp/ must include a .feature file change. For a price bump, add a @regression @issue-<N> scenario to instances/ppp/e2e/bdd/features/onboarding.feature asserting the new displayed prices in both currencies. Example:
@regression @issue-10117
Scenario: CPD Home signup shows the $299 AUD / £159 GBP price
Given I am on the PPP sign-up page
When I select the CPD Home plan
Then the displayed annual price for CPD Home should be "$299.00" in AUD
And the displayed annual price for CPD Home should be "£159.00" in GBP
And the PPP Full Platform annual price should remain "$1,699.00" in AUD
And the PPP Full Platform annual price should remain "£549.00" in GBPIf the step definitions don't exist yet, add them to instances/ppp/e2e/bdd/features/steps/signup.steps.ts (or wherever signup steps live). Step definitions grow organically.
3.5 Run the CLAUDE.md verification gates
# From the repo root
pnpm tsc # all packages
cd api/backend-ppp && pnpm tsc && pnpm lint && pnpm lint:no-console
cd ../.. && cd instances/ppp && npx tsc --noEmit -p tsconfig-lint.json && pnpm lint && pnpm lint:no-console
cd ../.. && cd api/backend-ppp && npx tsc --noEmit -p tsconfig.test.json
cd ../.. && node .github/scripts/check-no-any.mjsAll must exit zero. If lint:no-console or check-no-any.mjs fail with shell-escape errors on Windows, that's a known host issue — the same checks run cleanly in Linux CI.
3.6 Commit, push, open PR
git add -A
git commit -m "feat(pricing): bump <plan> to <currency><amount> — fixes #<issue>"
git push -u origin <branch>
gh pr create --base uat --title "feat(pricing): ... - fixes #<issue>" --body "..."The PR title must include a closing keyword in the fixes #N / closes #N / resolves #N form so the issue auto-closes on merge. See CLAUDE.md for the rules.
4. Post-merge: going live
4.1 UAT
- Merge lands on
uat→ the CD workflow rebuilds theppp-uk-uatAzure Container App image and rolls out a new revision (~10–15 min) - The Cloudflare Pages UAT deploy publishes the new frontend at roughly the same time
- Once both are live, the new displayed price and the new
amountsent to Stripe both take effect on the next signup
No Stripe dashboard changes. No env var rotation. No manual ops.
4.2 Prod
- Promotion from UAT to Prod is a separate gated deploy (infra in
api/infra-azure/andapi/infra-cloudflare/) - After prod deploy, prod customers will be charged the new amount on their next CPD signup
4.3 Smoke test (UAT, then Prod)
- Open the UAT signup flow in a fresh browser session
- Register a throwaway test email
- Pick the plan whose price you changed
- Verify the displayed price in the payment step matches your new value (e.g.
$299.00 AUD (incl. GST) / annually) - Enter a Stripe test card:
4242 4242 4242 4242— successful card- Any future expiry, any 3-digit CVC, any postcode
- Complete the payment
- In the Stripe UAT dashboard → Payments, find the newest PaymentIntent and confirm:
amountmatches the new value in cents/pencecurrencymatches the active instance (audfor AU,gbpfor UK)metadata.accountTypematches the plan you picked
- Repeat in Prod with a real card only once UAT is confirmed — and only if you have explicit sign-off to touch Prod
Additional Stripe test cards for edge cases are listed in the Stripe test cards docs.
5. What Stripe's dashboard shows after a price change
Because PPP doesn't use Products/Prices, the Stripe dashboard will still show historical charges at the old amount — that's correct and expected. Each PaymentIntent is immutable; past signups will always show whatever amount was sent at the time they were created. You can't "retroactively update" past charges — and you shouldn't, because they represent real money that was charged.
Your new price only affects new PaymentIntents from the moment the new code is deployed. To reconcile:
- Before deploy: all new PaymentIntents use the old amount
- During deploy (revision cut-over): a small window where either amount could apply depending on which container revision serves the request
- After deploy: all new PaymentIntents use the new amount
- Past payments: unchanged forever, visible in Stripe dashboard at their original amount
If you need a hard cut-over with no ambiguity (e.g. legal compliance), coordinate the PR merge with a maintenance window where signups are disabled for a minute or two.
6. Handling existing subscribers
PPP's annual billing is not a Stripe Subscription — each annual renewal is a fresh PaymentIntent initiated by the customer or the app. This means:
- There is nothing to migrate server-side. Stripe has no recurring charge to update.
- Existing customers pay the new price on their next renewal. They see it in the UI before confirming the charge.
- If you need to honour the old price for existing customers, that's a product decision, not a Stripe operation — you'd need to implement a grandfather flag in the backend (e.g.
PLAN_PRICESbecomes a function of user creation date) and ship that as its own feature.
At the time of writing PPP is pre-revenue with no live users, so the "existing subscribers" question is moot. The moment there are real customers, review this section before shipping any price change.
7. If someone asks for "the Stripe Price ID"
There isn't one. Redirect them to this page. The common reasons people ask:
| Question | What they actually need |
|---|---|
| "What's the CPD Stripe Price ID so I can update it in the dashboard?" | Nothing — there's no Price object. Show them this page. |
"Can you rotate the STRIPE_CPD_PRICE_ID env var?" | That env var doesn't exist. Only STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY, and STRIPE_WEBHOOK_SECRET are used. |
| "We need a new Stripe Product for the $299 plan" | Not required — the backend doesn't look up Products, it posts an amount per PaymentIntent. |
| "I need to migrate existing subscribers to the new Price" | No Stripe Subscriptions exist. The "migration" happens naturally at annual renewal time. |
8. Future: migrating to Stripe Products / Subscriptions
If PPP ever adopts Stripe Subscriptions (recurring charges managed by Stripe), Stripe Checkout (hosted payment page), or Customer Portal (self-service billing), this runbook will need a new section:
- Create a Stripe Product for each plan (CPD Home, PPP Full Platform) in UAT and Prod
- Create Price objects per product per currency — Stripe Prices are immutable, so bumping a price means creating a new Price object and archiving the old one
- Store the Price IDs in env vars (e.g.
STRIPE_CPD_AUD_PRICE_ID) or in instance config - Rotate env vars on UAT and Prod Container Apps when prices change
- Migrate existing subscribers to new Price using the Stripe Subscription update API
Until that migration happens, none of step 1–5 applies. See #5111 and the discussion around whether to move to Subscriptions for the rationale that may eventually drive this.
Related
- Stripe Payments integration overview
- Canonical pricing constant source
- Stripe integration guide (
docs/site/integrations/stripe.md) CLAUDE.md— BDD-first rule, verification gates, commit message conventions