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.

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.

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.

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.

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).

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.

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.

To cancel without collecting the remaining debt, pass write_off: true. To stop the automated retries but leave the debt on record, pass cancel_retries: true — the contract stays CANCELLING with next_payment blank until the amount is paid by other means or written off.

Cancelling While a Payment Is In Flight: strict

A payment that has already been submitted to the gateway cannot be recalled. If a cancel finalises the contract to CANCELLED while such a payment is still pending, and that payment later declines, the declined amount lands on an already-closed contract.

By default a cancellation proceeds regardless — any in-flight payment resolves independently afterwards. If you need certainty that no payment remains unresolved after cancellation, pass strict: true: a cancel that would immediately finalise the contract (nothing outstanding, or write_off: true) is rejected while a payment is pending or unresolved on the contract. Wait for the payment to resolve, then cancel again.

strict has no effect on a cancel that lands in CANCELLING — the wind-down state stays open until every amount resolves, so an in-flight payment poses no risk there.

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 → Developer Options → Merchant View → Scheduler

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