Skip to main content
Scheduling a payment lets you specify the exact date you want the ACH transfer to initiate. Instead of processing immediately, the payment sits in a scheduled state and automatically submits to the ACH network on the morning of the chosen date. Scheduling uses the same POST /v1/payments endpoint as immediate payments — you simply add the scheduledAt field to your request body.

​
How scheduling works

Add scheduledAt (formatted as YYYY-MM-DD) to any POST /v1/payments request:
  • The date must be at least tomorrow — you cannot schedule a payment for today or a past date.
  • On the scheduled date, the payment initiates at 9:00 AM New York time (Eastern Time).
  • The payment status is scheduled from creation until the execution date, at which point it transitions to pending and then follows the normal processing flow.
Cleo Pay always uses New York time (ET/EST) for scheduled payment execution. If your servers are in a different timezone, make sure you account for the offset when choosing a date — a payment scheduled for 2024-06-15 fires at 9:00 AM Eastern on June 15th regardless of where your application runs.

​
Schedule a payment

Schedule a payment for a future date
The response includes a scheduledAt datetime (in ISO 8601 format) showing when the payment will execute:
Scheduled payment response
The scheduledAt timestamp in the response is stored in UTC. 2024-06-15T13:00:00Z corresponds to 9:00 AM Eastern Daylight Time (EDT, UTC−4) on June 15, 2024.

​
Clearing speed

The optional clearing field controls how quickly the ACH transfer settles after it is submitted:
Schedule with NEXT_AVAILABLE clearing
NEXT_AVAILABLE clearing must be enabled on your account before you can use it. If your account does not have this feature enabled, the request will return an error. Contact your Cleo Pay account manager to enable faster clearing.

​
Limitations

  • Held payments cannot be scheduled. Scheduling is not supported for contacts who have no bank account on file. If a contact’s paymentReady flag is false, creating a scheduled payment will result in an error. Ensure the contact has a verified bank account before scheduling.
  • Past dates are rejected. Supplying a scheduledAt date in the past or equal to today’s date returns a 422 Unprocessable Entity.
  • Cancellation window. A scheduled payment can be cancelled before its execution date. Once the payment transitions to pending on the morning of the scheduled date, cancellation may no longer be possible.

​
What happens if a scheduled payment fails?

If a scheduled payment fails after it is submitted to the ACH network (for example, due to insufficient funds or an invalid account), the payment status transitions to failed. Cleo Pay will notify you via webhook. You will need to investigate the failure reason and, if appropriate, create a new payment. Common causes of failure after scheduling:
  • The source bank account was closed or lost verification between the time of scheduling and execution.
  • Insufficient funds in the source account at execution time.
  • The receiving contact’s bank account details changed or became invalid.
Subscribe to payment webhook events to receive real-time notifications when a scheduled payment fails. See the Webhooks reference for details.