# Schedules endpoints

> Recurrence schedules that start runs of a workflow: create, pause, resume, run now and preview the next occurrences. Every operation with parameters, body, responses, errors and examples.

Source: https://developers.processcart.com/reference/schedules

Recurrence schedules that start runs of a workflow: create, pause, resume, run now and preview the next occurrences.

Schedules carry no `revision`, and no operation here reads `Expected-Revision` (the header, or the SDK's `expectedRevision` option, is ignored): an update applies to the schedule as it is stored, and the last write wins. Run now answers the new run with its `revision`.

Base URL `https://app.processcart.com/api/v1`. Every operation below is also in the [OpenAPI document](https://developers.processcart.com/openapi.json) and the [interactive reference](https://developers.processcart.com/reference).

| Operation | Method and path | Scope |
| --- | --- | --- |
| [List schedules](#listSchedules) | <code class="pc-docs-wrap">GET /v1<wbr>/schedules</code> | Scope `schedules:manage` |
| [Create a schedule](#createSchedule) | <code class="pc-docs-wrap">POST /v1<wbr>/schedules</code> | Scope `schedules:manage` |
| [Get a schedule](#getSchedule) | <code class="pc-docs-wrap">GET /v1<wbr>/schedules<wbr>/{id}</code> | Scope `schedules:manage` |
| [Update a schedule](#updateSchedule) | <code class="pc-docs-wrap">PATCH /v1<wbr>/schedules<wbr>/{id}</code> | Scope `schedules:manage` |
| [Delete a schedule](#deleteSchedule) | <code class="pc-docs-wrap">DELETE /v1<wbr>/schedules<wbr>/{id}</code> | Scope `schedules:manage` |
| [Pause a schedule](#pauseSchedule) | <code class="pc-docs-wrap">POST /v1<wbr>/schedules<wbr>/{id}<wbr>/pause</code> | Scope `schedules:manage` |
| [Resume a schedule](#resumeSchedule) | <code class="pc-docs-wrap">POST /v1<wbr>/schedules<wbr>/{id}<wbr>/resume</code> | Scope `schedules:manage` |
| [Start a run from a schedule now](#runScheduleNow) | <code class="pc-docs-wrap">POST /v1<wbr>/schedules<wbr>/{id}<wbr>/run</code> | Scope `schedules:manage` |
| [Preview a schedule's next occurrences](#previewSchedule) | <code class="pc-docs-wrap">GET /v1<wbr>/schedules<wbr>/{id}<wbr>/preview</code> | Scope `schedules:manage` |

## GET /v1/schedules
**List schedules.** Scope `schedules:manage` · the key's allowlist narrows the rows (never a 403 — rows outside it are absent) · paginated (`{ data, nextCursor, hasMore }`). Operation id `listSchedules` · [open in the API reference](https://developers.processcart.com/reference#tag/schedules/GET/v1/schedules).

Lists the workspace's recurrence schedules, newest first, each with its recurrence, presets, enabled state and next occurrences. Filter by `workflowId` or `enabled`. `updatedSince` turns the list into an incremental sync ordered by `updatedAt` ascending (inclusive). A key restricted to workflows or folders lists only the schedules of workflows inside its allowlist.

**Query parameters** (an unknown parameter is a 422 `validation_failed` with `errors[].code = "unknown_parameter"`)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workflowId` | string (uuid) | no |  |
| `enabled` | boolean | no |  |
| `updatedSince` | string (date-time) | no | Incremental sync: only items whose `updatedAt` is at or after this instant (inclusive), ordered by `updatedAt` ascending; an explicit conflicting `sort` / `order` is a 422. Overlap by a minute and dedupe: a Run by `(id, revision)`, any other item (workflow, view, webhook, schedule, automation rule) by `(id, updatedAt)` — a higher `revision` or a later `updatedAt` replaces the copy you hold, an equal one is unchanged. |
| `limit` | integer | no |  |
| `cursor` | string | no | The `nextCursor` of the previous page. Opaque, and bound to the query that produced it — a cursor from a different filter or sort is a 422. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [ScheduleList](https://developers.processcart.com/reference/schemas#schedulelist) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 422 | `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "data": [
    {
      "id": "12b83373-b279-48e5-86b1-c88e71c9ed29",
      "workflowId": "39b74b11-d796-42e5-972f-d2a20b5ce7b1",
      "workflow": {
        "id": "39b74b11-d796-42e5-972f-d2a20b5ce7b1",
        "name": "Order fulfillment"
      },
      "name": "Weekly order review",
      "description": "Every Monday at 9:00 AM",
      "recurrence": {
        "freq": "weekly",
        "interval": 1,
        "time": "09:00",
        "startDate": "2026-11-02",
        "weekly": {
          "days": [
            "mon"
          ]
        }
      },
      "timezone": "America/Los_Angeles",
      "namePattern": "{{workflow}} — {{date}}",
      "presetValues": {
        "amount": 250,
        "customer": "Acme Corp"
      },
      "assignmentOverrides": {
        "review": [
          {
            "kind": "user",
            "userId": "d4a284fd-cdc8-43c1-8933-084a811fc33e"
          }
        ],
        "wrapup": [
          {
            "kind": "group",
            "groupId": "98257cc7-dce3-4ca7-a310-ecf91b75e201"
          }
        ]
      },
      "enabled": true,
      "disabledReason": null,
      "lastError": null,
      "consecutiveFailures": 0,
      "nextRunAt": "2026-11-02T17:00:00.000Z",
      "nextOccurrences": [
        "2026-11-02T17:00:00.000Z",
        "2026-11-09T17:00:00.000Z",
        "2026-11-16T17:00:00.000Z"
      ],
      "lastRunAt": null,
      "latestRun": {
        "id": "1185793a-e8fc-4470-a359-826794842cef",
        "name": "Order fulfillment — Oct 10, 2026",
        "startedAt": "2026-10-11T05:27:53.467Z"
      },
      "presetMismatches": [],
      "createdBy": null,
      "createdAt": "2026-10-11T05:27:50.731Z",
      "updatedAt": "2026-10-11T05:27:52.873Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```


## POST /v1/schedules
**Create a schedule.** Scope `schedules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key`. Operation id `createSchedule` · [open in the API reference](https://developers.processcart.com/reference#tag/schedules/POST/v1/schedules).

Creates a schedule that starts runs of one published workflow on a recurrence (daily, weekly, monthly or yearly, at a time on a 5-minute step), with a run-name pattern, preset field values (every required kickoff field needs one; a preset outside its field's bounds is refused with 422, `errors[].code` `invalid_value`) and optional per-task assignees. `timezone` defaults to the workspace's. A recurrence with no future occurrence is refused. Audited. A key restricted to workflows or folders sees only the schedules of workflows inside its allowlist; any other schedule answers 403 `not_allowed_for_key`.

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |

**Request body** — `application/json`, [ScheduleConfig](https://developers.processcart.com/reference/schemas#scheduleconfig)

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `workflowId` | [Uuid](https://developers.processcart.com/reference/schemas#uuid) | yes |  |
| `name` | string | yes |  |
| `recurrence` | [Recurrence](https://developers.processcart.com/reference/schemas#recurrence) | yes |  |
| `timezone` | string | no |  |
| `namePattern` | string | no |  |
| `presetValues` | object (key → [CanonicalValue](https://developers.processcart.com/reference/schemas#canonicalvalue)) | no |  |
| `assignmentOverrides` | object (key → [AutomationAssignee](https://developers.processcart.com/reference/schemas#automationassignee)[]) | no |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 201 | Created. `Location` names the new resource. | [Schedule](https://developers.processcart.com/reference/schemas#schedule) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key; `workflow_not_runnable` — Workflow not runnable. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress; `workflow_not_published` — Workflow not published; `workflow_trashed` — Workflow is in Trash. | [Problem](https://developers.processcart.com/errors) |
| 413 | `payload_too_large` — Payload too large. | [Problem](https://developers.processcart.com/errors) |
| 415 | `unsupported_media_type` — Unsupported media type. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 403 [`workflow_not_runnable`](https://developers.processcart.com/errors#workflow_not_runnable) — Workflow not runnable
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 409 [`workflow_not_published`](https://developers.processcart.com/errors#workflow_not_published) — Workflow not published
- 409 [`workflow_trashed`](https://developers.processcart.com/errors#workflow_trashed) — Workflow is in Trash
- 413 [`payload_too_large`](https://developers.processcart.com/errors#payload_too_large) — Payload too large
- 415 [`unsupported_media_type`](https://developers.processcart.com/errors#unsupported_media_type) — Unsupported media type
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example request**

```json
{
  "workflowId": "39b74b11-d796-42e5-972f-d2a20b5ce7b1",
  "name": "Weekly order review",
  "recurrence": {
    "freq": "weekly",
    "interval": 1,
    "time": "09:00",
    "startDate": "2026-11-02",
    "weekly": {
      "days": [
        "mon"
      ]
    }
  },
  "presetValues": {
    "customer": "Acme Corp",
    "amount": 250
  },
  "assignmentOverrides": {
    "review": [
      {
        "kind": "user",
        "userId": "d4a284fd-cdc8-43c1-8933-084a811fc33e"
      }
    ],
    "wrapup": [
      {
        "kind": "group",
        "groupId": "98257cc7-dce3-4ca7-a310-ecf91b75e201"
      }
    ]
  }
}
```

**Example response** (201)

```json
{
  "id": "12b83373-b279-48e5-86b1-c88e71c9ed29",
  "workflowId": "39b74b11-d796-42e5-972f-d2a20b5ce7b1",
  "workflow": {
    "id": "39b74b11-d796-42e5-972f-d2a20b5ce7b1",
    "name": "Order fulfillment"
  },
  "name": "Weekly order review",
  "description": "Every Monday at 9:00 AM",
  "recurrence": {
    "freq": "weekly",
    "interval": 1,
    "time": "09:00",
    "startDate": "2026-11-02",
    "weekly": {
      "days": [
        "mon"
      ]
    }
  },
  "timezone": "America/Los_Angeles",
  "namePattern": "{{workflow}} — {{date}}",
  "presetValues": {
    "amount": 250,
    "customer": "Acme Corp"
  },
  "assignmentOverrides": {
    "review": [
      {
        "kind": "user",
        "userId": "d4a284fd-cdc8-43c1-8933-084a811fc33e"
      }
    ],
    "wrapup": [
      {
        "kind": "group",
        "groupId": "98257cc7-dce3-4ca7-a310-ecf91b75e201"
      }
    ]
  },
  "enabled": true,
  "disabledReason": null,
  "lastError": null,
  "consecutiveFailures": 0,
  "nextRunAt": "2026-11-02T17:00:00.000Z",
  "nextOccurrences": [
    "2026-11-02T17:00:00.000Z",
    "2026-11-09T17:00:00.000Z",
    "2026-11-16T17:00:00.000Z"
  ],
  "lastRunAt": null,
  "latestRun": null,
  "presetMismatches": [],
  "createdBy": null,
  "createdAt": "2026-10-11T05:27:50.731Z",
  "updatedAt": "2026-10-11T05:27:50.731Z"
}
```


## GET /v1/schedules/{id}
**Get a schedule.** Scope `schedules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it). Operation id `getSchedule` · [open in the API reference](https://developers.processcart.com/reference#tag/schedules/GET/v1/schedules/{id}).

Returns one schedule with its recurrence in words, presets, assignment overrides, enabled state and pause reason, failure counter, next occurrences, newest run and any presets the published workflow no longer accepts. A key restricted to workflows or folders sees only the schedules of workflows inside its allowlist; any other schedule answers 403 `not_allowed_for_key`.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [Schedule](https://developers.processcart.com/reference/schemas#schedule) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 422 | `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "id": "12b83373-b279-48e5-86b1-c88e71c9ed29",
  "workflowId": "39b74b11-d796-42e5-972f-d2a20b5ce7b1",
  "workflow": {
    "id": "39b74b11-d796-42e5-972f-d2a20b5ce7b1",
    "name": "Order fulfillment"
  },
  "name": "Weekly order review",
  "description": "Every Monday at 9:00 AM",
  "recurrence": {
    "freq": "weekly",
    "interval": 1,
    "time": "09:00",
    "startDate": "2026-11-02",
    "weekly": {
      "days": [
        "mon"
      ]
    }
  },
  "timezone": "America/Los_Angeles",
  "namePattern": "{{workflow}} — {{date}}",
  "presetValues": {
    "amount": 250,
    "customer": "Acme Corp"
  },
  "assignmentOverrides": {
    "review": [
      {
        "kind": "user",
        "userId": "d4a284fd-cdc8-43c1-8933-084a811fc33e"
      }
    ],
    "wrapup": [
      {
        "kind": "group",
        "groupId": "98257cc7-dce3-4ca7-a310-ecf91b75e201"
      }
    ]
  },
  "enabled": true,
  "disabledReason": null,
  "lastError": null,
  "consecutiveFailures": 0,
  "nextRunAt": "2026-11-02T17:00:00.000Z",
  "nextOccurrences": [
    "2026-11-02T17:00:00.000Z",
    "2026-11-09T17:00:00.000Z",
    "2026-11-16T17:00:00.000Z"
  ],
  "lastRunAt": null,
  "latestRun": {
    "id": "1185793a-e8fc-4470-a359-826794842cef",
    "name": "Order fulfillment — Oct 10, 2026",
    "startedAt": "2026-10-11T05:27:53.467Z"
  },
  "presetMismatches": [],
  "createdBy": null,
  "createdAt": "2026-10-11T05:27:50.731Z",
  "updatedAt": "2026-10-11T05:27:52.873Z"
}
```


## PATCH /v1/schedules/{id}
**Update a schedule.** Scope `schedules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key`. Operation id `updateSchedule` · [open in the API reference](https://developers.processcart.com/reference#tag/schedules/PATCH/v1/schedules/{id}).

Changes any subset of `name`, `recurrence`, `timezone`, `namePattern`, `presetValues` and `assignmentOverrides` (presets and overrides are checked against the workflow's current published version). A new recurrence or zone recomputes the next run from now. `workflowId` cannot change, and `enabled` is not part of the configuration — use the pause and resume operations (422 `unknown_key` on `enabled`). A preset outside its field's bounds is refused (422 `invalid_value`). Audited.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |

**Request body** — `application/json`, [SchedulePatch](https://developers.processcart.com/reference/schemas#schedulepatch)

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no |  |
| `recurrence` | [Recurrence](https://developers.processcart.com/reference/schemas#recurrence) | no |  |
| `timezone` | string | no |  |
| `namePattern` | string | no |  |
| `presetValues` | object (key → [CanonicalValue](https://developers.processcart.com/reference/schemas#canonicalvalue)) | no |  |
| `assignmentOverrides` | object (key → [AutomationAssignee](https://developers.processcart.com/reference/schemas#automationassignee)[]) | no |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [Schedule](https://developers.processcart.com/reference/schemas#schedule) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key; `workflow_not_runnable` — Workflow not runnable. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress; `workflow_not_published` — Workflow not published; `workflow_trashed` — Workflow is in Trash. | [Problem](https://developers.processcart.com/errors) |
| 413 | `payload_too_large` — Payload too large. | [Problem](https://developers.processcart.com/errors) |
| 415 | `unsupported_media_type` — Unsupported media type. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 403 [`workflow_not_runnable`](https://developers.processcart.com/errors#workflow_not_runnable) — Workflow not runnable
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 409 [`workflow_not_published`](https://developers.processcart.com/errors#workflow_not_published) — Workflow not published
- 409 [`workflow_trashed`](https://developers.processcart.com/errors#workflow_trashed) — Workflow is in Trash
- 413 [`payload_too_large`](https://developers.processcart.com/errors#payload_too_large) — Payload too large
- 415 [`unsupported_media_type`](https://developers.processcart.com/errors#unsupported_media_type) — Unsupported media type
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example request**

```json
{
  "name": "Weekly order review (Mondays)"
}
```

**Example response** (200)

```json
{
  "id": "12b83373-b279-48e5-86b1-c88e71c9ed29",
  "workflowId": "39b74b11-d796-42e5-972f-d2a20b5ce7b1",
  "workflow": {
    "id": "39b74b11-d796-42e5-972f-d2a20b5ce7b1",
    "name": "Order fulfillment"
  },
  "name": "Weekly order review (Mondays)",
  "description": "Every Monday at 9:00 AM",
  "recurrence": {
    "freq": "weekly",
    "interval": 1,
    "time": "09:00",
    "startDate": "2026-11-02",
    "weekly": {
      "days": [
        "mon"
      ]
    }
  },
  "timezone": "America/Los_Angeles",
  "namePattern": "{{workflow}} — {{date}}",
  "presetValues": {
    "amount": 250,
    "customer": "Acme Corp"
  },
  "assignmentOverrides": {
    "review": [
      {
        "kind": "user",
        "userId": "d4a284fd-cdc8-43c1-8933-084a811fc33e"
      }
    ],
    "wrapup": [
      {
        "kind": "group",
        "groupId": "98257cc7-dce3-4ca7-a310-ecf91b75e201"
      }
    ]
  },
  "enabled": true,
  "disabledReason": null,
  "lastError": null,
  "consecutiveFailures": 0,
  "nextRunAt": "2026-11-02T17:00:00.000Z",
  "nextOccurrences": [
    "2026-11-02T17:00:00.000Z",
    "2026-11-09T17:00:00.000Z",
    "2026-11-16T17:00:00.000Z"
  ],
  "lastRunAt": null,
  "latestRun": {
    "id": "1185793a-e8fc-4470-a359-826794842cef",
    "name": "Order fulfillment — Oct 10, 2026",
    "startedAt": "2026-10-11T05:27:53.467Z"
  },
  "presetMismatches": [],
  "createdBy": null,
  "createdAt": "2026-10-11T05:27:50.731Z",
  "updatedAt": "2026-10-11T05:27:55.743Z"
}
```


## DELETE /v1/schedules/{id}
**Delete a schedule.** Scope `schedules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key`. Operation id `deleteSchedule` · [open in the API reference](https://developers.processcart.com/reference#tag/schedules/DELETE/v1/schedules/{id}).

Deletes the schedule. Runs it already created stay; their `schedule` member reads null afterwards. Audited.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 204 | Done; no body. | — |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable


## POST /v1/schedules/{id}/pause
**Pause a schedule.** Scope `schedules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key`. Operation id `pauseSchedule` · [open in the API reference](https://developers.processcart.com/reference#tag/schedules/POST/v1/schedules/{id}/pause).

Stops the schedule from creating runs (reason `manual`). Pausing a paused schedule answers 200 unchanged and keeps its reason. Audited.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [Schedule](https://developers.processcart.com/reference/schemas#schedule) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "id": "12b83373-b279-48e5-86b1-c88e71c9ed29",
  "workflowId": "39b74b11-d796-42e5-972f-d2a20b5ce7b1",
  "workflow": {
    "id": "39b74b11-d796-42e5-972f-d2a20b5ce7b1",
    "name": "Order fulfillment"
  },
  "name": "Weekly order review",
  "description": "Every Monday at 9:00 AM",
  "recurrence": {
    "freq": "weekly",
    "interval": 1,
    "time": "09:00",
    "startDate": "2026-11-02",
    "weekly": {
      "days": [
        "mon"
      ]
    }
  },
  "timezone": "America/Los_Angeles",
  "namePattern": "{{workflow}} — {{date}}",
  "presetValues": {
    "amount": 250,
    "customer": "Acme Corp"
  },
  "assignmentOverrides": {
    "review": [
      {
        "kind": "user",
        "userId": "d4a284fd-cdc8-43c1-8933-084a811fc33e"
      }
    ],
    "wrapup": [
      {
        "kind": "group",
        "groupId": "98257cc7-dce3-4ca7-a310-ecf91b75e201"
      }
    ]
  },
  "enabled": false,
  "disabledReason": "manual",
  "lastError": null,
  "consecutiveFailures": 0,
  "nextRunAt": null,
  "nextOccurrences": [],
  "lastRunAt": null,
  "latestRun": null,
  "presetMismatches": [],
  "createdBy": null,
  "createdAt": "2026-10-11T05:27:50.731Z",
  "updatedAt": "2026-10-11T05:27:51.759Z"
}
```


## POST /v1/schedules/{id}/resume
**Resume a schedule.** Scope `schedules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key`. Operation id `resumeSchedule` · [open in the API reference](https://developers.processcart.com/reference#tag/schedules/POST/v1/schedules/{id}/resume).

Turns a paused schedule back on. Resuming never catches up: occurrences missed while paused are skipped and the next run is the first occurrence after now. A schedule whose end date has passed is refused with 409 `schedule_ended` (change its recurrence first). A schedule whose workflow is unpublished answers 409 `workflow_not_published`, one in Trash 409 `workflow_trashed`, and an archived one 403 `workflow_not_runnable`. Resuming a running schedule answers 200 unchanged. Audited.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [Schedule](https://developers.processcart.com/reference/schemas#schedule) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key; `workflow_not_runnable` — Workflow not runnable. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress; `schedule_ended` — Schedule ended; `workflow_not_published` — Workflow not published; `workflow_trashed` — Workflow is in Trash. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 403 [`workflow_not_runnable`](https://developers.processcart.com/errors#workflow_not_runnable) — Workflow not runnable
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 409 [`schedule_ended`](https://developers.processcart.com/errors#schedule_ended) — Schedule ended
- 409 [`workflow_not_published`](https://developers.processcart.com/errors#workflow_not_published) — Workflow not published
- 409 [`workflow_trashed`](https://developers.processcart.com/errors#workflow_trashed) — Workflow is in Trash
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "id": "12b83373-b279-48e5-86b1-c88e71c9ed29",
  "workflowId": "39b74b11-d796-42e5-972f-d2a20b5ce7b1",
  "workflow": {
    "id": "39b74b11-d796-42e5-972f-d2a20b5ce7b1",
    "name": "Order fulfillment"
  },
  "name": "Weekly order review",
  "description": "Every Monday at 9:00 AM",
  "recurrence": {
    "freq": "weekly",
    "interval": 1,
    "time": "09:00",
    "startDate": "2026-11-02",
    "weekly": {
      "days": [
        "mon"
      ]
    }
  },
  "timezone": "America/Los_Angeles",
  "namePattern": "{{workflow}} — {{date}}",
  "presetValues": {
    "amount": 250,
    "customer": "Acme Corp"
  },
  "assignmentOverrides": {
    "review": [
      {
        "kind": "user",
        "userId": "d4a284fd-cdc8-43c1-8933-084a811fc33e"
      }
    ],
    "wrapup": [
      {
        "kind": "group",
        "groupId": "98257cc7-dce3-4ca7-a310-ecf91b75e201"
      }
    ]
  },
  "enabled": true,
  "disabledReason": null,
  "lastError": null,
  "consecutiveFailures": 0,
  "nextRunAt": "2026-11-02T17:00:00.000Z",
  "nextOccurrences": [
    "2026-11-02T17:00:00.000Z",
    "2026-11-09T17:00:00.000Z",
    "2026-11-16T17:00:00.000Z"
  ],
  "lastRunAt": null,
  "latestRun": null,
  "presetMismatches": [],
  "createdBy": null,
  "createdAt": "2026-10-11T05:27:50.731Z",
  "updatedAt": "2026-10-11T05:27:52.873Z"
}
```


## POST /v1/schedules/{id}/run
**Start a run from a schedule now.** Scope `schedules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key`. Operation id `runScheduleNow` · [open in the API reference](https://developers.processcart.com/reference#tag/schedules/POST/v1/schedules/{id}/run).

Starts one run right away with the schedule's name pattern, presets and assignment overrides — paused or not, outside the recurrence. Returns the new Run (`startedBy: "schedule"`, `schedule` set, `scheduledFor: null`, `revision: 1`) and an absolute `Location`. Presets the published workflow no longer accepts are skipped; a required kickoff field without a preset is refused with 422 `required_fields_unsatisfied`. Audited.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 201 | Created. `Location` names the new resource. | [Run](https://developers.processcart.com/reference/schemas#run) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key; `workflow_not_runnable` — Workflow not runnable. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress; `workflow_not_published` — Workflow not published; `workflow_trashed` — Workflow is in Trash. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `required_fields_unsatisfied` — Required fields unsatisfied; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 403 [`workflow_not_runnable`](https://developers.processcart.com/errors#workflow_not_runnable) — Workflow not runnable
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 409 [`workflow_not_published`](https://developers.processcart.com/errors#workflow_not_published) — Workflow not published
- 409 [`workflow_trashed`](https://developers.processcart.com/errors#workflow_trashed) — Workflow is in Trash
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`required_fields_unsatisfied`](https://developers.processcart.com/errors#required_fields_unsatisfied) — Required fields unsatisfied
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (201)

```json
{
  "id": "1185793a-e8fc-4470-a359-826794842cef",
  "name": "Order fulfillment — Oct 10, 2026",
  "status": "active",
  "priority": "none",
  "labels": [],
  "labelDetails": [],
  "dueAt": null,
  "keyDate": null,
  "revision": 1,
  "updatedAt": "2026-10-11T05:27:53.910Z",
  "startedAt": "2026-10-11T05:27:53.467Z",
  "startedBy": "schedule",
  "startedByUserId": null,
  "schedule": {
    "id": "12b83373-b279-48e5-86b1-c88e71c9ed29",
    "name": "Weekly order review"
  },
  "scheduledFor": null,
  "completedAt": null,
  "deletedAt": null,
  "workflow": {
    "id": "39b74b11-d796-42e5-972f-d2a20b5ce7b1",
    "name": "Order fulfillment"
  },
  "versionId": "9973fead-8dbf-4719-9a61-9dc7b126a7f4",
  "url": "https://app.processcart.com/runs/1185793a-e8fc-4470-a359-826794842cef",
  "tasks": [
    {
      "key": "details",
      "title": "Details",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "review",
      "title": "Review",
      "kind": "approval",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [
        {
          "kind": "user",
          "userId": "d4a284fd-cdc8-43c1-8933-084a811fc33e"
        }
      ],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "stop",
      "title": "Sign-off",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "wrapup",
      "title": "Wrap up",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": true,
      "dueAt": null,
      "assignees": [
        {
          "kind": "group",
          "groupId": "98257cc7-dce3-4ca7-a310-ecf91b75e201"
        }
      ],
      "completedAt": null,
      "completedByUserId": null
    }
  ],
  "fields": [
    {
      "key": "customer",
      "label": "Customer",
      "type": "text",
      "format": "none",
      "taskKey": "details",
      "value": "Acme Corp",
      "formatted": "Acme Corp",
      "visible": true
    },
    {
      "key": "order_code",
      "label": "Order code",
      "type": "text",
      "format": "custom",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "memo",
      "label": "Memo",
      "type": "textarea",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "quantity",
      "label": "Quantity",
      "type": "number",
      "format": "number",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "amount",
      "label": "Amount",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 250,
      "formatted": "$250.00",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "ship_date",
      "label": "Ship date",
      "type": "date",
      "format": "date",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "start_time",
      "label": "Start time",
      "type": "time",
      "format": "time",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "gift_wrap",
      "label": "Gift wrap",
      "type": "dropdown",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "choices": [
        "Yes",
        "No"
      ]
    },
    {
      "key": "tags",
      "label": "Tags",
      "type": "multi_choice",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "choices": [
        "A",
        "B",
        "C"
      ]
    },
    {
      "key": "agree",
      "label": "Agree",
      "type": "checkbox",
      "format": null,
      "taskKey": "details",
      "value": false,
      "formatted": "No",
      "visible": true
    },
    {
      "key": "contact_email",
      "label": "Contact email",
      "type": "email",
      "format": "email",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "website",
      "label": "Website",
      "type": "url",
      "format": "url",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "phone",
      "label": "Phone",
      "type": "phone",
      "format": "phone",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "owner",
      "label": "Owner",
      "type": "members",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "steps",
      "label": "Steps",
      "type": "subtasks",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "items": [
        {
          "key": "photos",
          "label": "Photos"
        },
        {
          "key": "invoice",
          "label": "Invoice"
        }
      ]
    },
    {
      "key": "contract",
      "label": "Contract",
      "type": "file",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "double_amount",
      "label": "Double amount",
      "type": "formula",
      "format": "currency",
      "taskKey": "details",
      "value": 500,
      "formatted": "$500.00",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": false
    }
  ]
}
```


## GET /v1/schedules/{id}/preview
**Preview a schedule's next occurrences.** Scope `schedules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it). Operation id `previewSchedule` · [open in the API reference](https://developers.processcart.com/reference#tag/schedules/GET/v1/schedules/{id}/preview).

Returns the next `count` (1–10, default 3) times the schedule creates a run, as UTC instants. For a paused schedule, the occurrences a resume would produce (counted from now); empty once its end date has passed.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Query parameters** (an unknown parameter is a 422 `validation_failed` with `errors[].code = "unknown_parameter"`)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `count` | integer | no |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [ScheduleOccurrences](https://developers.processcart.com/reference/schemas#scheduleoccurrences) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 422 | `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "occurrences": [
    "2026-11-02T17:00:00.000Z",
    "2026-11-09T17:00:00.000Z",
    "2026-11-16T17:00:00.000Z"
  ]
}
```