Amend a charge

Changes the amount and/or the due date of one open charge on a contract, in place, without touching the rest of the contract. The literal due date now collects the charge against the server clock. Because the contract's next payment date and its collection plan follow the charge, this is also the way a single instalment of a charge schedule, or the single charge of a scheduled one-off payment, is moved or re-priced; Amend a contract's terms delegates a scheduled one-off's amount and scheduled_date to this same charge edit.

Where you can do this

Merchant View: Charge (Save)
API: Update a charge (PUT /charges/{charge_id}) — body carries amount and/or due (due may be the literal "now") and no status change; a status change is charge.void

Before you start

The charge is ACTIVE or FAILING as the API reports it. COMPLETED, CANCELLED, FAILED, WRITTENOFF and in-flight (PENDING, UNRESOLVED, UNCONFIRMED) charges cannot be amended.
The charge belongs to a contract the session can see. On a plain one-off (no recurring, no scheduled_date, no charges[]) only the due date can change.
No contract status is required server-side; a still-open charge on a suspended, cancelled or completed contract is accepted. Merchant View offers Edit only while the contract is ACTIVE, PENDING, SUSPENDED, UNRESOLVED or FAILING.
No payment for this charge is in flight if the amount is being reduced.

Inputs

Input	Required	Meaning and constraints
amount	no	Decimal string. Greater than zero and not below `paid_amount`. A value equal to the current amount is a no-op. Refused on a plain one-off contract when it differs from the current amount.
due	no	ISO 8601 date-time (read to the second as `yyyy-MM-ddTHH:mm:ss`; a zone suffix or milliseconds are not interpreted) or the literal `now`, which Shuttle replaces with the time of the request. Not more than 7 days before now, unless on the same calendar day as the charge's current due date. A date on the same calendar day as the current due date counts as unchanged unless `amount` also changes.
status	no	Must be absent or equal to the charge's current status for this function. `WRITTENOFF` on an open charge is Write off a charge.

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 fields go inside a `charge` object: `{"charge": {... }}`. The record itself is identified by the id in the URL, not in the body	The API	VALIDATION_ERROR: "API body error: missing charge object"
The charge, and then its contract, must exist and be visible to the session	The API	NOT_FOUND: "charge not found" / NOT_FOUND for the contract
A `status` that differs from the charge's current status routes the call elsewhere: `WRITTENOFF` writes the charge off (Write off a charge); any other status on a written-off charge writes it back on; nothing else in the body is applied on either path	The API	(routed; see Write off a charge)
On a plain one-off contract (due now: no `recurring`, `scheduled_date` or `charges[]`) the amount cannot change; a due-date change on such a charge is still forwarded and applied	The API	VALIDATION_ERROR: "cannot change amount on non-recurring charges"
Only an ACTIVE or FAILING charge can be amended; every other status, including the in-flight ones, is refused. Merchant View mirrors this and offers Edit only on such a charge	The API; Merchant View screen mirrors	INVALID: "This charge is complete and cannot be updated" / control hidden
The amount must be above zero and not below what is already paid. Merchant View mirrors the paid floor inline	The API; Merchant View screen mirrors	INVALID: "Invalid value for field amount." / "You cannot edit this value to be less than the amount already paid ()."
The due date cannot be more than 7 days in the past, except a date on the same calendar day as the charge's current due date. There is no service-layer 24-hour limit on this call (contrast Amend a scheduled contract's instalments)	The API	INVALID: "Invalid value for field due."
A request that changes nothing (same amount, and a due date on the same calendar day as the current one) is a no-op: nothing is saved, no webhook is raised, the charge is returned unchanged	The API	200 OK, nothing changes
Merchant View offers Edit only on a recurring, charge-schedule or scheduled one-off contract, so a plain one-off's charge is never edited from the screen even though the server accepts a due-date change on it. By design: a one-off's single charge is going to be paid, so moving its date is not a thing an operator should be doing.	Merchant View screen only	control hidden
Re-splitting the charge into instalments is delegated to the client's payment rule; if it returns no instalments the edit fails after validation	The API	INVALID: "(BOLT-7006) Internal Error: Failed to create charge"
The contract is locked for the edit; if another process holds it for longer than 30 seconds the edit fails	The API	INVALID with Shuttle's lock code BOLT-7059 and no message text
Merchant View asks for confirmation, but does not refuse, when `due` is `now` or less than five minutes ahead ("By setting the next charge immediately, this charge may be created and processed before you have a chance to change your mind. Are you sure?"); its picker allows any time from the start of today, so a time earlier today reaches the server and is accepted under the 7-day rule. By design: the API allows any time from the start of the day so an integrator can choose the exact time future payments go out. The screen does not offer that, because on a screen it is more likely to be a mistake than a choice.	Merchant View screen only	confirmation modal

What happens

The charge carries the new amount and/or due date; the response returns the charge as stored, so a due of now comes back as the time the server used. The charge's outstanding_amount is the new amount less what is paid and written off.
On a recurring contract the contract's next_payment moves with the charge (to the edited charge's due date on a fixed or variable recurring contract; to the earliest unpaid charge's due date on a charge schedule) and the next collection attempt is re-planned for that date. A due date of now or in the past collects shortly after the save; the money moves then, not at the time of the edit.
On a scheduled one-off (a one-off with scheduled_date) the contract's amount and scheduled_date follow the charge.
On a charge-schedule contract (charges[]) an amount change also changes the contract's amount to the new sum of its charges.
A CHARGE.UPDATE webhook is sent when something changed (CONTRACT.UPDATE instead when the contract is a plain one-off); nothing is sent for a no-op. No email or SMS is sent and no gateway is called by the edit itself.
Merchant View's contract and charge screens refresh through the object-update stream.

Who can do this

Roles: Admin only today; intended for Support as well, and being aligned.