> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleo-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Schedule a Future Payment with Cleo Pay

> Schedule ACH payments for a future date using the Cleo Pay API. Payments execute at 9:00 AM New York time on the chosen date.

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.

<Tip>
  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.
</Tip>

***

## Schedule a payment

```bash title="Schedule a payment for a future date" theme={null}
curl --request POST \
  --url https://api.cleo-pay.com/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "payableId": "payable_01hwxyz123",
    "bankAccountId": "ba_01hwxyz456",
    "scheduledAt": "2024-06-15"
  }'
```

The response includes a `scheduledAt` datetime (in ISO 8601 format) showing when the payment will execute:

```json title="Scheduled payment response" theme={null}
{
  "payableId": "payable_01hwxyz123",
  "payments": [
    {
      "id": "pmt_01hwxyz789",
      "status": "scheduled",
      "amountCents": 150000,
      "bankAccountId": "ba_01hwxyz456",
      "scheduledAt": "2024-06-15T13:00:00Z",
      "createdAt": "2024-06-01T10:00:00Z"
    }
  ]
}
```

<Note>
  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.
</Note>

***

## Clearing speed

The optional `clearing` field controls how quickly the ACH transfer settles after it is submitted:

| Value            | Behavior                                                  |
| ---------------- | --------------------------------------------------------- |
| `STANDARD`       | Standard ACH settlement timeline (default).               |
| `NEXT_AVAILABLE` | Uses the next available ACH window for faster settlement. |

```bash title="Schedule with NEXT_AVAILABLE clearing" theme={null}
curl --request POST \
  --url https://api.cleo-pay.com/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "contactId": "contact_01hwxyz111",
    "amountCents": 75000,
    "bankAccountId": "ba_01hwxyz456",
    "scheduledAt": "2024-06-20",
    "clearing": "NEXT_AVAILABLE"
  }'
```

<Info>
  `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.
</Info>

***

## 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](/reference/webhooks) for details.