What we did

Added a reconciliation path that claims an invoice with an optimistic version check, calls Stripe, then commits the outcome. Run state lives in Redis under its own TTL, so a shared-cache eviction can’t drop a run mid-flight. The whole path sits behind billing.reconcile_v2, defaulted off.

Changes

• app/Billing/InvoiceReconciler.phpNew service. Claims an invoice with a version check, calls Stripe, writes the outcome back in a single transaction.
• app/Repositories/InvoiceRepository.phpAdded claimForReconciliation() — the only place the version check is issued.
• database/migrations/2026_07_14_101122_add_version_to_invoices.phpAdds invoices.version. No down migration: invoice_events is ~40M rows and the rollback would lock it.
• config/billing.phpRegisters the billing.reconcile_v2 flag, off by default.

Considerations

• Chose: Optimistic locking on invoices.version
  Instead of: A row lock held across the Stripe call
  The lock would be held for the full network round trip, blocking every other writer on that row.
• Chose: Reconciling synchronously in the webhook handler
  Instead of: Dispatching a queued job
  The follow-up webhook can arrive before the job is picked up, which reorders events that have to stay ordered.
• Chose: Retrying three times
  Instead of: Unbounded retries with backoff
  Stripe idempotency keys expire after 24h — retries past that window create a second charge instead of replaying the first.
• Chose: Keeping the legacy status column
  Instead of: Dropping it as part of this ticket
  The finance export still reads it. Removing it is its own change with its own rollout.

Implications

• invoices now carries a version column. Any writer that bypasses claimForReconciliation() will lose its update silently.
• Nothing changes in production until ops enable billing.reconcile_v2 after the backfill.
• This migration has to be rolled back by hand — there is no down path.
• BillingService is untouched, so the refactor in PROJ-501 can still land independently.

Not done

• EUR was not exercised. It takes a different rounding path in the Stripe response and needs its own pass.
• The reconciliation success metric is not wired up; the analytics pipeline doesn’t accept custom counters yet.
• No backfill for invoices created before this change — they stay on the legacy path until reconciled.

Benefits

• Reconciliation no longer blocks other writers on the invoice row.
• A cache eviction mid-run can’t leave an invoice half-reconciled.
• The rollout is reversible at the flag, without a deploy.