Skip to content

feat: offer "Charge now" — with a confirmation — when a subscription is not yet due - #62

Merged
wzul merged 1 commit into
mainfrom
feat/charge-now-confirmation
Sep 25, 2026
Merged

wzul merged 1 commit into
mainfrom
feat/charge-now-confirmation

Conversation

@wzul

@wzul wzul commented Sep 25, 2026

Copy link
Copy Markdown
Collaborator

feat: offer "Charge now" — with a confirmation — when a subscription is not yet due

"Retry now" was offered for any live subscription, including one whose next
payment was still in the future. Pressing it there could only ever answer
"nothing to retry", because nothing was due. The button was reachable but
pointless, which is how its message came to be reported as confusing.

It now splits into two actions that differ only by the calendar:

already due     -> "Retry now"      collects the outstanding cycle
not due yet     -> "Charge now"     collects that cycle EARLY

"Charge now" requires a second, explicit confirmation before anything is
charged. admin_charge_now only asks: it renders what will be charged, the
amount, and when it was scheduled, and the charge itself is a separate
chip_charge_now_confirm request with its own nonce. A stray click, a browser
prefetch or an impatient double-click cannot move money. The eligibility is
re-checked at the moment of the charge rather than trusted from the earlier
screen, because that window is exactly when a cron run could have collected
the cycle already.

The correctness work is in what an EARLY charge does NOT do. The scheduled
cycle has not happened, so:

  • it does not advance chip_sub_next_payment. The billing day is an agreement
    and collecting early is not a reason to shift every later cycle forward;
    the scheduled cycle still runs.
  • it does not consume an installment from chip_sub_remaining.
  • a failure does not touch the retry ladder, does not put the subscription on
    hold, and cannot expire it. The customer was not in arrears, so dunning them
    for it would be wrong, and expiring a healthy subscription because an
    operator tried to collect early would be worse.

That last point is subtle in the code: an early charge claims no next date,
which is the same signal an ordinary renewal uses to mean "final instalment,
expire now". The two are told apart explicitly rather than by the claim alone.

The eligibility predicate is expressed as two calls to the same blocker that
decides an ordinary charge — chargeable with the date ignored, but blocked by
it — so the button can never appear for a subscription the charge itself would
refuse. A cancelled subscription, or one with no stored card, gets no button.

Also fixes a related false report: can_retry() now returns false for a
subscription that is merely not due yet, which is what put "Retry now" on a
row where it could not work.

Verified end to end on a live install:

click "Charge now"  -> confirmation screen, nothing charged
confirm             -> &charge=charged, collected via the gateway
after               -> chip_sub_next_payment unchanged, status active,
                       retry count still 0

Potential Risks & Review Items

  • This action moves real money immediately, outside the billing schedule.
    The confirmation step is the only thing between an operator's click and a
    charge, which is why it exists and why the eligibility is re-checked after
    it. Review that second check as the load-bearing control, not the first.
  • $any_time is a new parameter on is_due(), blocking_reason(),
    plan_renewal() and charge_renewal(). It defaults to false everywhere, and
    the cron path never passes it — pinned by a test, because an accidental
    true there would charge every subscription on every run.
  • The cron's due-query still selects on chip_sub_next_payment <= now, so an
    early charge does not make a subscription appear due.
  • An early charge records an addon transaction and fires the renewed event, so
    the gateway's own transaction is what reconciles it. It is a second
    collection of the same cycle by design; if that is not wanted, the feature
    should not be offered rather than made silently idempotent.
  • The confirmation screen uses wp_die() with wp_kses_post(), following the
    existing admin-post handlers in this file. It is an operator-facing page, not
    a public one.

…is not yet due

"Retry now" was offered for any live subscription, including one whose next
payment was still in the future. Pressing it there could only ever answer
"nothing to retry", because nothing was due. The button was reachable but
pointless, which is how its message came to be reported as confusing.

It now splits into two actions that differ only by the calendar:

    already due     -> "Retry now"      collects the outstanding cycle
    not due yet     -> "Charge now"     collects that cycle EARLY

"Charge now" requires a second, explicit confirmation before anything is
charged. `admin_charge_now` only asks: it renders what will be charged, the
amount, and when it was scheduled, and the charge itself is a separate
`chip_charge_now_confirm` request with its own nonce. A stray click, a browser
prefetch or an impatient double-click cannot move money. The eligibility is
re-checked at the moment of the charge rather than trusted from the earlier
screen, because that window is exactly when a cron run could have collected
the cycle already.

The correctness work is in what an EARLY charge does NOT do. The scheduled
cycle has not happened, so:

- it does not advance `chip_sub_next_payment`. The billing day is an agreement
  and collecting early is not a reason to shift every later cycle forward;
  the scheduled cycle still runs.
- it does not consume an installment from `chip_sub_remaining`.
- a failure does not touch the retry ladder, does not put the subscription on
  hold, and cannot expire it. The customer was not in arrears, so dunning them
  for it would be wrong, and expiring a healthy subscription because an
  operator tried to collect early would be worse.

That last point is subtle in the code: an early charge claims no next date,
which is the same signal an ordinary renewal uses to mean "final instalment,
expire now". The two are told apart explicitly rather than by the claim alone.

The eligibility predicate is expressed as two calls to the same blocker that
decides an ordinary charge — chargeable with the date ignored, but blocked by
it — so the button can never appear for a subscription the charge itself would
refuse. A cancelled subscription, or one with no stored card, gets no button.

Also fixes a related false report: `can_retry()` now returns false for a
subscription that is merely not due yet, which is what put "Retry now" on a
row where it could not work.

Verified end to end on a live install:

    click "Charge now"  -> confirmation screen, nothing charged
    confirm             -> &charge=charged, collected via the gateway
    after               -> chip_sub_next_payment unchanged, status active,
                           retry count still 0

## Potential Risks & Review Items

- **This action moves real money immediately, outside the billing schedule.**
  The confirmation step is the only thing between an operator's click and a
  charge, which is why it exists and why the eligibility is re-checked after
  it. Review that second check as the load-bearing control, not the first.
- `$any_time` is a new parameter on `is_due()`, `blocking_reason()`,
  `plan_renewal()` and `charge_renewal()`. It defaults to false everywhere, and
  the cron path never passes it — pinned by a test, because an accidental
  `true` there would charge every subscription on every run.
- The cron's due-query still selects on `chip_sub_next_payment <= now`, so an
  early charge does not make a subscription appear due.
- An early charge records an addon transaction and fires the renewed event, so
  the gateway's own transaction is what reconciles it. It is a second
  collection of the same cycle by design; if that is not wanted, the feature
  should not be offered rather than made silently idempotent.
- The confirmation screen uses `wp_die()` with `wp_kses_post()`, following the
  existing admin-post handlers in this file. It is an operator-facing page, not
  a public one.
@wzul
wzul force-pushed the feat/charge-now-confirmation branch from 31c0b3d to fd0ac42 Compare September 25, 2026 08:03
@wzul
wzul merged commit 4b44a0e into main Sep 25, 2026
7 checks passed
@wzul
wzul deleted the feat/charge-now-confirmation branch September 25, 2026 08:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant