Reschedule the next payment

Moves the date of the next collection attempt on a recurring or instalment contract, typically to retry arrears sooner (or later) than the automatic retry schedule would. It does not create or move a charge: the contract's regular next charge date is untouched, and the money collected is whatever is already outstanding on the contract's existing charges. There is no dedicated endpoint; it is a contract update whose body carries only next_payment.

How it differs from Move the next charge: next_charge is the date the next charge is created on a recurring contract (the schedule itself); next_payment is the date the payment scheduler next tries to collect what is already owed. When the next charge is created, the scheduler resets next_payment to that moment anyway, which is why a retry date after next_charge is refused.

Where you can do this

Merchant View: Edit an upcoming charge or payment (Save)
API: Update a contract (PUT /contracts/{contract_id}) — body carries next_payment only; the literal "now" is accepted

Before you start

The contract is recurring or an instalment schedule (recurring, or with a charge schedule). A one-off contract is refused; a single future-dated payment (a one-off with a scheduled_date) silently ignores the field.
The contract is in progress: ACTIVE, PENDING, FAILING or UNRESOLVED. A cancelling, cancelled, completed or failed contract is refused; a suspended one accepts the request but the date does not stick (see Rules).
Something is outstanding on the contract; a date set on a contract with nothing outstanding is cleared again by the save.

Inputs

Input	Required	Meaning and constraints
next_payment	yes	Date-time of the next collection attempt, `yyyy-MM-ddTHH:mm:ss` against the server clock, or the literal `now`. Not later than the contract's next_charge. On an instalment contract, not earlier than the next unpaid instalment's due date. A blank value is not a supported way to clear the date (see Rules).

Rules

Checked by the API means Shuttle refuses the request however it is sent; a screen name means only that screen refuses it, and a direct API call would be accepted.

Rule	Checked by	What you see
The body must carry a contract object	The API	VALIDATION_ERROR: "API body error: missing contract object"
A one-off contract (`ONEOFF` with no scheduled date) cannot be rescheduled	The API	VALIDATION_ERROR: "cannot update non-recurring contracts"
A scheduled single payment (a one-off with a `scheduled_date`) is collected on its due date, changed through `scheduled_date` (Amend a contract's terms); a next_payment sent for one is not forwarded	The API	200, next_payment unchanged
An irregular contract (a legacy type the API does not create) is not editable through this call	The API	INVALID: "Invalid value for field contract (type IRREGULAR does not support scheduled charge edits)."
A cancelling contract is not editable	The API	INVALID: "Invalid value for field contract (status PAYMENTCANCELLING is not editable)."
A cancelled, completed or failed contract is not editable; there is no clear-the-date exception on this path (that exception exists only inside the resume flow, Resume a contract)	The API	INVALID: "Invalid value for field contract (status PAYMENTCANCELLED is not editable)." (or COMPLETED, FAILED)
The retry date must not be later than the contract's next_charge, when it has one; "now" is compared as the current time. Merchant View mirrors this with a toast and caps the date picker at next_charge	The API and Merchant View screen	VALIDATION_ERROR: "Invalid retry date, must not be later than next charge date"; admin app: "The next payment can't be scheduled later than the next charge."
On a charge-schedule contract the date cannot be earlier than the due date of the next instalment with money outstanding	The API	INVALID (BOLT-7086): "whenNextPayment cannot be earlier than the next unpaid charge due date (date)"
On an instalment contract the date only sticks when that next unpaid instalment is already overdue; if it is still in the future, the save's scheduler replaces the date with the instalment's own collection date (due date less any advance notice) and answers 200	The API	200, next_payment replaced with the instalment's collection date
The save also clears the date when the contract is in ERROR status, has an unattributed amount, has a zero amount, has nothing outstanding, or is an UNRESOLVED contract created before 2022	The API	200, next_payment absent
Merchant View offers Schedule payment only while the contract is in progress, not PENDING, and any existing next_payment is more than five minutes away; the server has no such rule and accepts a new date on a PENDING contract. By design: somebody scheduling a payment while one is already processing has probably misread the screen, so it is not offered. The API applies no such rule.	Merchant View screen only (not the API)	control hidden
Combining next_payment with other fields makes this a different function: with status SUSPENDED the suspend wins and next_payment is dropped (Suspend a contract); with bypass_validation Shuttle refuses the mix; with payment_method the explicit date overrides the retry-now default (Change the payment method on a contract); with terms it is Amend a contract's terms	The API	INVALID (BOLT-7086): "newStatus cannot be combined with other contract edit fields" for the bypass_validation case; otherwise as the linked function

What happens

The contract keeps its status and its regular next_charge; only the date of the next collection attempt moves, and no new charge is created.
The response carries the contract with next_payment as saved. It is absent when the save cleared the date (a suspended contract, or nothing outstanding), and on an instalment contract whose next unpaid instalment is not yet overdue it is replaced by that instalment's own collection date.
A CONTRACT.UPDATE webhook is raised.
At the new date (brought forward by the payment method's advance notice where it has one; at once for "now") everything already due on the contract is collected in a single attempt, which then runs as Collect a contract's arrears now does.
If that attempt fails, the automatic retry schedule sets the next date or, once retries are exhausted, clears it. When the next charge is created, the regular schedule takes over.

Who can do this

Roles: Admin only today; intended for Support as well, and being aligned.
Admin app: the screen needs payment_contract and the admin option recurring_edit; the option gates Merchant View only and is not checked by the server.