---
title: "Register a schedule"
method: POST
path: "/schedules/v1"
tags: ["Schedules"]
---

# Register a schedule

`POST /schedules/v1`

Registers a new schedule (recurring or explicit) against an existing, authorized consent.

## Headers

- `Idempotency-Key` string, required

## Request body

- CreateScheduleRequest
  - `reference` string, nullable — A default reference applied to payments created by this schedule.
  - `purpose` string, nullable — The payment purpose code applied to payments created by this schedule. Optional; omit when not applicable.
  - `consent_id` string, uuid, required — The id of the authorized consent the schedule is registered against.
  - `schedule` union, required — The definition of the schedule to register. Discriminated by `kind`.
    - object — A schedule that repeats on a fixed cadence for a fixed amount.
      - `kind` string, required — The schedule kind discriminator. Always `RECURRING` for this variant.
      - `recurrence` ScheduleRecurrence, required — Describes the cadence of a recurring schedule.
        - `unit` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR', required — The time unit on which a recurring schedule repeats. - `DAY` — the schedule repeats every day. - `WEEK` — the schedule repeats every week. - `MONTH` — the schedule repeats every month. - `YEAR` — the schedule repeats every year.
      - `amount` ScheduleAmount, required — A monetary amount for a scheduled payment.
        - `value` number, required — The amount of money in the currency specified.
        - `currency` string, required — The currency of the amount.
      - `start_date` string, date, nullable — The date of the first payment.
      - `end_date` string, date, nullable — The date after which no further payments are made. Open-ended when omitted.
    - object — A schedule made up of an explicit list of dated payments.
      - `kind` string, required — The schedule kind discriminator. Always `EXPLICIT` for this variant.
      - `executions` ScheduleExecutionEntry[], required — The explicit list of planned payment executions.
        - `execute_on` string, date, required — The date on which this payment should be executed.
        - `amount` ScheduleAmount, required — A monetary amount for a scheduled payment.
          - `value` number, required — The amount of money in the currency specified.
          - `currency` string, required — The currency of the amount.
        - `reference` string, nullable — Optional per-execution reference passed to the bank.

## Response `201`

The schedule was registered.

- CreateScheduleResponse
  - `schedule_id` string, uuid, required — The id of the newly registered schedule.
  - `consent_id` string, uuid, required — The id of the consent the schedule was registered against.
  - `status` 'PENDING' | 'ACTIVE' | 'PAUSED' | 'CONSENT_BLOCKED' | 'CANCELLED' | 'COMPLETED', required — The lifecycle status of a schedule. - `PENDING` — registered, not yet active. - `ACTIVE` — active; payments are attempted on their due dates. - `PAUSED` — temporarily paused; no payments attempted until resumed. - `CONSENT_BLOCKED` — the underlying consent is no longer usable. - `CANCELLED` — terminated by the client or due to consent state. - `COMPLETED` — all planned payments have been executed.
  - `links` ScheduleLinks, required — Hypermedia links for the actions available on a schedule. Only `self` is always present; the remaining links are included only when the corresponding action is currently available.
    - `self` string, required — Link to the schedule itself.
    - `cancel` string, nullable — Link to cancel the schedule, when the action is available.
    - `pause` string, nullable — Link to pause the schedule, when the action is available.
    - `resume` string, nullable — Link to resume the schedule, when the action is available.
    - `upcoming_payments` string, nullable — Link to the upcoming payments of the schedule, when available.

---

[API](https://skmtc.net/leantech/apis/auth.md) · [All operations](https://skmtc.net/leantech/apis/auth/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/leantech/auth/revisions/c2e46d54d886/schema)