Scheduler

Any payment that isn't a single pay-now runs through Shuttle's scheduler — the background process that picks up charges on their due date, attempts payment against the contract's saved payment method, and manages automatic retries when payments fail.

This page is the model: what the scheduler does and why. What one operation accepts, refuses and changes is per operation in Business Rules, which the screens and the API both follow, and each section below links to the ones that matter.

Which Payment Models Use the Scheduler

Precision

The scheduler is a polled background process, not a real-time trigger. A charge due at 09:00:00 will normally be attempted within a few minutes of that time. Treat a charge's due date as "no earlier than this time" rather than "exactly this time".

next_charge vs next_payment

Two timestamp fields on a contract describe what will happen next:

On a recurring contract, as soon as a charge is created, next_charge is advanced by one frequency cycle and next_payment is set to the imminent attempt date for the newly-created charge. If the payment fails, next_charge is unaffected but next_payment is pushed out by the applicable retry delay.

On scheduled one-time and scheduled-charges contracts, next_charge is not used — next_payment tracks the next scheduled attempt directly.

Moving either of them by hand is an operation in its own right: Move the next charge and Reschedule the next payment say what each accepts, and what one does to the other.

Advance Notice (BACS, SEPA, ACH and similar)

Some payment methods need to be submitted to the bank a number of days before the target settlement date. When a gateway tokenises one of these methods (e.g., BACS, SEPA, ACH via GoCardless; SEPA via Stripe) it returns an advanced_notice_hours value on the payment method indicating how far in advance the bank needs to be notified.

When a payment method has advanced_notice_hours set, Shuttle adjusts scheduling so payments are initiated that many hours before the due date:

• For a recurring contract, the next charge is generated advanced_notice_hours before next_charge, and next_payment is pulled forward by the same window so the gateway receives the instruction in time for the bank to settle on the target date.
• For scheduled one-time and scheduled charges, next_payment is similarly pulled forward from each charge's due date.

The due date itself is unchanged — the customer's account is still debited on the due date. What changes is when the invoice/charge is raised in Shuttle and when the payment instruction leaves for the gateway.

Representative values returned by gateways today:

Cards and wallet payment methods do not set advanced_notice_hours; they are scheduled on the due date itself.

The practical implication: for merchants on these schemes, charges on a contract may appear in reporting/dashboards several days before their due date. That is expected behaviour, not a bug.

Retries

Automated payment attempts that fail are retried automatically. Shuttle applies different retry schedules depending on the failure type.

Technical Error Retries

Used when an attempt fails for an infrastructure reason — gateway offline, connectivity problem, internal error. The intent is to retry quickly because the underlying problem is often transient.

Decline Retries

Used when the issuing bank declines — insufficient funds, card blocked, limit exceeded. The intent is to space attempts so funds have time to become available.

When an Automated Retry Is Not Attempted

A retry is only scheduled if there is a usable payment method to retry against. In the cases below no further automated attempt is made against the outstanding amount: next_payment is cleared and retry_complete is set to true.

None of this stops the next charge being attempted. When a new charge is created, the scheduler always makes one payment attempt against it — even when the payment method is already known to be unusable and the attempt cannot reach the gateway. That attempt is recorded against the charge, so the reason the invoice was not collected is visible where the invoice is rather than the charge simply sitting unpaid with no explanation.

What is suppressed is the retries. Repeat attempts exist to recover money from a method that might succeed later — funds arriving in the account, a temporary block lifted. There is nothing to recover by attempting a method that cannot be charged at all, so no retry is scheduled and the contract waits for either a new payment method or the next charge.

A single pay-now payment is never retried automatically — it does not go through the scheduler at all.

In all of these cases the contract stays in FAILING with its arrears intact. Collection resumes once the cause is dealt with: attach a working method with Change the payment method on a contract, then Collect a contract's arrears now to attempt payment without waiting for the next charge.

Retry State

• retry_count on the contract tracks how many retries have been attempted.
• Once the schedule is exhausted, retry_complete is set to true — no further automated retries are made against that outstanding amount.
• New charges on a recurring contract still have their own fresh payment attempt even after retry_complete is set — it only suppresses retries against the existing overdue amount.
• A successful payment resets retry_count to 0 and clears retry_complete.

Retry schedules are configured per merchant; the values above are defaults and may be adjusted by your account manager.

Gateway-Managed Retries

Some gateways run their own retry policy and override Shuttle's decline-retry schedule. At present this applies to GoCardless: once GoCardless has a live mandate and has notified the customer of an upcoming collection, it can retry a declined collection faster than Shuttle's default schedule because the advance-notice lead time has already been served. In those cases Shuttle defers to the gateway's own retry cadence for declines.

Technical-error retries still use Shuttle's schedule — a technical failure means the instruction never reached the gateway, so there is nothing for the gateway to retry. Shuttle retries the instruction using the Technical Error Retries schedule above.

The practical implication for merchants on GoCardless (and any future gateway with equivalent behaviour): a declined collection may be retried on a different cadence to what is shown in the Decline Retries table. Consult the gateway's documentation for its schedule.

Collecting arrears by hand, rather than waiting for the next attempt, is Collect a contract's arrears now.

Contract Completion & Cancellation

A contract managed by the scheduler ends in one of two terminal states: COMPLETED (it ran its natural course) or CANCELLED (it was ended deliberately).

When a Contract Completes

The completion check runs every time a contract is saved — after each payment, write-off, or update. A contract transitions to COMPLETED when all of the following are true:

• No outstanding amount remains (everything charged has been paid or written off)
• No unresolved amount remains
• No further charge will be generated (next_charge is blank)
• No payment is currently in flight

What that means per payment model:

On completion, the CONTRACT.COMPLETE webhook fires (it also fires on transition to CANCELLED or FAILED — see Webhooks).

What each operation does to a contract's outstanding amount, and therefore to its completion, is set out per operation in Business Rules: Write off a charge, Amend a contract's terms and Suspend a contract.

Holding a Contract Open: keep_active_until

Once a contract is COMPLETED, it can no longer be amended. If you need to apply changes after the final payment has been collected — for example, a mid-term amendment that adds a closing charge — set keep_active_until on the contract (via update contract, or when creating the checkout) before the final payment lands.

While keep_active_until is set to a future date, a fully-settled contract stays ACTIVE instead of completing. When the date passes, the scheduler wakes the contract and completes it — provided nothing is outstanding at that point. Amendments made during the window (extra charges, changed amounts) are processed as normal.

Points to note:

• It applies to contracts only (recurring and scheduled charges) — it has no effect on a one-time payment.
• It suppresses completion only. Cancellation is unaffected: a contract cancelled during the window transitions to CANCELLED as usual.
• When the date passes on a fully-settled contract, completion happens even if the contract hasn't reached its configured number of occurrences — the hold was explicit and has expired.
• To release the hold early, update the contract with keep_active_until set to a past date (or blank) — the contract then completes as soon as nothing is outstanding.
• A suspended contract is not completed while suspended; the window is re-evaluated when the contract is resumed.

What an amendment made during that window is allowed to change is in Amend a contract's terms and Amend a scheduled contract's instalments.

Cancellation and the CANCELLING Status

Cancelling a contract (cancel contract) stops future charges immediately — next_charge is cleared and no new charges are generated. What happens next depends on whether an amount is still outstanding:

CANCELLING is a wind-down state: the contract accepts no new charges, but the scheduler keeps attempting to collect the outstanding amount, including automated retries. Once the outstanding amount is either collected or written off, the contract transitions to CANCELLED.

The thing to hold on to is that cancelling stops new charges, not collection: CANCELLING keeps collecting what is already owed, and a cancelled contract still reports what was owed because its charges are left exactly as they were. Clearing a balance for good is a separate act — Write off a charge.

A payment already submitted to the gateway cannot be recalled, so a cancel that finalises the contract while one is in flight can leave a declined amount landing on a closed contract. There is a parameter to refuse that case rather than accept it.

The parameters — writing off as you cancel, stopping the retries without writing off, and refusing to finalise over an in-flight payment — and exactly what each refuses and when, are in Terminate a contract. Resume a contract covers coming back from CANCELLING.

Enabling the Scheduler View for Merchants

Merchants can see and manage upcoming scheduled activity (future charges, retry status, failing contracts) from a Scheduler page in their merchant view. This page is hidden by default.

If your platform uses scheduled one-time, recurring, or scheduled charges, enable the Scheduler page for your merchants:

Developer portal → the application's Developer tab → Configure Merchant View → Scheduler

Once enabled, merchants on your platform will see the Scheduler option in their navigation.