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.

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.