Redesign checkout data model & flow for a multi-product cart

[ArendPeter]

Question

Part of the Phase 1 Payment System: Design & Build Map. Design backend data model & Stripe integration flow for Phase 1 payments designed a single-product flow (buy voter-limit blocks via a tier-select modal). The organizer-facing plan has since shifted to a cart: an "Upgrade Election" button opens a popout where the user can add multiple line items to one Stripe Checkout Session — starting with voter-limit blocks in batches, with other add-on types (e.g. a custom slug) anticipated but explicitly not built in this map (see Out of scope).

How should the checkout data model, Checkout Session creation, and webhook fulfillment generalize to support multiple line items and future product types, while Phase 1 still ships only the voter-limit product?

[github-actions]

👋 Hi @ArendPeter! Thank you for taking on this issue!

To help us track progress and support you effectively, please provide the following information:

Availability for this week:

My estimated ETA for completing this issue:

Feel free to ask questions in the #bettervoting Slack channel if you need any help!

[ArendPeter]

Resolution

Generalizing to a cart, decided as follows:

• One stripeCheckoutSessionsDB row = one Checkout Session (one transaction), not one row per line item. A cart with multiple items still produces a single row.
• product column becomes a JSON blob — an array of cart line items, each one an exact snapshot of the price_data sent to Stripe for that item (name, description, image, unit amount) plus a type discriminator and type-specific payload (e.g. { type: 'voter_limit_block', blocks: 2 }). This is deliberately redundant with what's sent to Stripe — it's an audit snapshot of what the user was shown and intended to buy, not a normalized reference.
• voter_count_granted stays its own top-level column, computed as the sum across whichever line items are voter-limit blocks (0 if none). Kept because most transactions touch it and it's the cheap way to confirm an election's voter-limit history without parsing the JSON blob.
• A small in-repo product catalog / type registry is the generalization point: each product type knows how to price itself, build its own price_data (name/description/image), validate a requested quantity, and apply its own fulfillment effect. Phase 1 registers exactly one entry — voter-limit blocks. This is what "designed generically" means here: adding a future add-on (e.g. custom slug) is a new catalog entry plus new cart-UI affordance, not a rework of the session/table/endpoint/webhook plumbing. No second product type is being built now — see the map's Out of scope section, unchanged.
• Checkout Session endpoint (Build Checkout Session creation endpoint (cart validation + Stripe session) #1586) takes a cart request — a list of { type, quantity } items — and re-derives every item's price/name/description/image from the in-repo catalog server-side (never trusts client-sent price/copy, same non-negotiable as before, now applied per-item). It rejects any type not in the Phase-1 catalog (i.e. anything but voter-limit blocks) rather than erroring generically, since only one type exists to accept.
• Webhook fulfillment (Build Stripe webhook endpoint, applyVoterLimitPurchase fulfillment & receipt email #1587) runs a single Postgres transaction that: flips the session row to paid, and applies every line item's fulfillment effect (via the same catalog dispatch used at checkout-creation time) — in Phase 1 that's just the voter_limit increment, but the transaction wraps "however many effects the row's line items produce," not a single hardcoded update. All effects commit together or none do.
• Frontend ("Upgrade Election" button → cart popout, prototype ticket Prototype Add Voters payment modal & Upgrade tier button #1569): built as a generic cart (add/remove line items, running total, "Checkout with Stripe" button), even though Phase 1's "add" affordance only offers voter-limit blocks in batches — there's nothing else in the catalog to add yet.

Left as fog, not decided here: whether the frontend needs to poll transaction status after the Stripe-hosted redirect back to the success page, since the webhook may not have landed yet. Recorded in the map's Not yet specified.

This supersedes the single-product parts of #1568's design. Downstream: #1586, #1587, #1569 rewritten to match; #1584 / PR #1589 (still open, unmerged) needs a follow-up schema amendment (product varchar → product jsonb) — flagged on that PR and on #1584 rather than pushed here.