allowances: credit the shortfall when OC's billing day truncates a paid cycle

Open Collective aligns recurring charges onto the collective's common billing
day, so a mid-month joiner is charged again before a full month is up: they pay
for a full month and receive less than one. Credit the missing ALLOWANCE (the
flat MEMBER_BUDGET pro-rated for the days lost, unrounded) as non-expiring
credits.

- derived from the collective's real per-order charge history, on every sweep;
  any consecutive pair on the same order < a full month apart is truncated
- idempotent on the OC charge reference (dedupe on the charge, not the member)
- skips and logs any cycle whose dates cannot be determined
- ledger reason names the cycle; the notice is staged and defaults OFF
- [redacted member reference]'s remediated charge is excluded by ref

Tests: tests/test_allowance_shortfall.py (pure derivation).
This commit is contained in:
inference-bot committed 2026-11-04 20:01:10 +00:00
1 parent c468b61d3e
commit db64dac235
3 files changed
+529

No files matched your search

+26
View File
@@ -149,6 +149,32 @@ changes nothing; `mode=send` performs renewals and sends the reminder and
requires `ALLOWANCE_POLICY=on`. Deactivation additionally requires
`ALLOWANCE_DEACTIVATE=on`.
### Allowance shortfall (a paid cycle OC truncated)
Open Collective aligns every recurring charge onto the collective's common
billing day, so a member who joins mid-month is charged again well before a full
month has elapsed — they pay for a full month and receive less than one. The
co-op's remedy: credit the missing **allowance** (the flat `MEMBER_BUDGET`
pro-rated for the days lost, `FULL_PAID_MONTH_DAYS = 30`, unrounded) as
non-expiring credits — the same balance that extends the allowance and is spent
only after it. It is never a share of what they paid.
The set is derived FROM DATA, on every sweep (`POST /admin/sweep` calls
`reconcile_allowance_shortfalls`, as does `POST /admin/shortfall-credits`):
each MONTHLY order's real charge history is read from Open Collective, and any
consecutive pair on the SAME order less than a full month apart is a truncated
cycle. Two subscriptions a member happens to hold are judged separately; a gap
whose dates cannot be determined is skipped and logged. Each credit is keyed to
the specific OC charge that caused it (`credit_ledger.reference` = the charge
`publicId`), so a re-run credits nothing twice — dedupe is on the charge, not
the member — and the ledger `reason` names the cycle so a member's question is
answerable from it.
Member notices ride the same pass, but default OFF
(`ALLOWANCE_SHORTFALL_EMAILS=off`); set it to `on` to send the staged notice,
at most once per charge (`shortfall_notices`). `mode=report` on
`/admin/shortfall-credits` previews the affected set and changes nothing.
### Energy & carbon metrics
The daily snapshot also computes energy (Wh) and carbon (gCO₂e) from output tokens,