docs(admin): explain why a Stripe price is replaced, not edited (BUNYIP-511) #526

Merged

longjacksonle merged 1 commit from docs/BUNYIP-511-explain-price-immutability into main

2026-08-12 19:22:04 +02:00

longjacksonle commented

2026-08-12 19:16:39 +02:00

Owner

What

Adds a plain "why" to the Replace control on the admin Stripe Prices page (BUNYIP-511). It already created-new-and-archived correctly, but only said "Stripe cannot change an existing price" - which invites the question why.

The disclosure now leads with Why replace instead of edit? and answers it: a Stripe price is immutable because live subscriptions and past invoices reference that exact price object, so changing its amount would retroactively alter what existing customers agreed to pay and what their invoices say; Stripe only permits changing a price's active state, nickname or metadata, never its amount. A second line restates what a replace does and what it deliberately leaves alone (existing subscriptions, grandfathered prices).

Copy-only change to price_replace_details; a test asserts the explanation renders.

Verification

just check-container green. Screenshot in the chat shows the expanded Replace control with the explanation.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GkNbvEq6awuMRULFCiYKe3

## What Adds a plain "why" to the Replace control on the admin Stripe Prices page (BUNYIP-511). It already created-new-and-archived correctly, but only said "Stripe cannot change an existing price" - which invites the question why. The disclosure now leads with **Why replace instead of edit?** and answers it: a Stripe price is immutable because live subscriptions and past invoices reference that exact price object, so changing its amount would retroactively alter what existing customers agreed to pay and what their invoices say; Stripe only permits changing a price's active state, nickname or metadata, never its amount. A second line restates what a replace does and what it deliberately leaves alone (existing subscriptions, grandfathered prices). Copy-only change to `price_replace_details`; a test asserts the explanation renders. ## Verification `just check-container` green. Screenshot in the chat shows the expanded Replace control with the explanation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01GkNbvEq6awuMRULFCiYKe3

longjacksonle added 1 commit

2026-08-12 19:16:39 +02:00

docs(admin): explain why a Stripe price is replaced, not edited (BUNYIP-511)

E2E / PR gate (pull_request) Successful in 27s

Details

Check / fmt + clippy + build + tests (pull_request) Successful in 5m22s

Details

Create release / Create release from merged PR (pull_request) Has been skipped

Details

61cd03a09d

The Replace control on the admin Stripe Prices page did the right thing but only said "Stripe cannot change an existing price". Admins reasonably ask why. The disclosure now leads with "Why replace instead of edit?" and explains it: a Stripe price is immutable because live subscriptions and past invoices reference that exact price object, so changing its amount would retroactively alter what existing customers agreed to pay and what their invoices say; Stripe only permits changing a price's active state, nickname or metadata, never its amount. A second line restates what a replace does (new price at the new amount, archive the old, move the catalog mapping and entitlements across, existing subscriptions and grandfathered prices stay put).

Copy-only change to `price_replace_details`; a test asserts the explanation and the word "immutable" are rendered. just check-container is green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GkNbvEq6awuMRULFCiYKe3

longjacksonle scheduled this pull request to auto merge when all checks succeed

2026-08-12 19:17:10 +02:00