# Platform Schedule Configuration Migration

This page covers v1-to-v2 migration notes for platform schedule configuration and time-slot data.

For the v2-native model, start with
[Platform Schedule Configuration](/docs/guides/resource-guides/platform-schedule-configuration). Use
[Publication Scheduling](/docs/guides/editorial-workflows/publication-scheduling) for publication-level schedules and the
[Platforms API reference](/api/platform/platforms) for exact schemas and validation.

## Scope

Covered v2 surfaces:

| Area | v2 surface |
|------|------------|
| Read platforms | `GET /api/v2/platforms`, `GET /api/v2/platforms/{id}`, `GET /api/v2/platforms/external-id/{externalId}` |
| Create platform schedule mode | `POST /api/v2/platforms` with `weeklySchedule`, `manualSchedule`, or default weekly schedule |
| Replace platform schedule data | `PUT /api/v2/platforms/{id}` |
| Patch platform schedule data | `PATCH /api/v2/platforms/{id}` |
| Time-slot IDs for publication scheduling | `timeSlots[]` in platform responses |

## Schedule Mode Changes

v2 exposes one schedule mode per platform:

| Mode | v2 field | Migration impact |
|------|----------|------------------|
| Weekly | `weeklySchedule` | Send explicit weekday flags. |
| Manual | `manualSchedule` | Send explicit issue dates. |

Non-null `weeklySchedule` and `manualSchedule` payloads are mutually exclusive.

:::caution{title="Omitting both schedule fields applies a default"}

When `POST /api/v2/platforms` omits both schedule fields, or sends both as `null`, v2 creates a
default weekly schedule with all seven weekdays set to `true`. Only omit or null both fields when
that default is intended.

:::

## Weekly Schedule Changes

Weekly schedule payloads use explicit day flags:

```json
{
  "weeklySchedule": {
    "mon": true,
    "tue": true,
    "wed": true,
    "thu": true,
    "fri": true,
    "sat": false,
    "sun": false
  }
}
```

When `weeklySchedule` is provided, all seven flags are required and `null` is invalid.

## Manual Schedule Changes

Manual schedules are arrays of publication dates:

```json
{
  "manualSchedule": [
    {
      "externalId": "issue-2026-01",
      "date": "2026-01-15",
      "note": "January issue"
    }
  ]
}
```

Client-impacting create rules:

- `manualSchedule` must not be empty.
- each entry requires `date`.
- `id` must be omitted on create.
- dates must be unique within the request.

## PUT And PATCH Changes

`PUT /api/v2/platforms/{id}` is full replacement for writable platform fields.

For schedule fields:

- a weekly platform must be replaced with `weeklySchedule`.
- a manual platform must be replaced with `manualSchedule`.
- `PUT` cannot switch a weekly platform to manual or a manual platform to weekly.
- a manual replacement list replaces the resulting manual date set.

`PATCH /api/v2/platforms/{id}` is presence-aware.

For manual platforms, `manualSchedule` in `PATCH` is an add/update instruction list:

- `manualSchedule: []` is a no-op.
- an entry without `id` and with `date` adds a manual date.
- an entry with `id` patches that existing date.
- use `DELETE /api/v2/platforms/{platformId}/manual-schedule/{manualScheduleId}` to delete an
  existing manual date.
- deleting the last remaining manual date through that DELETE endpoint is rejected.

`weeklySchedule: null` and `manualSchedule: null` are invalid in patch requests.

## Time-Slot Changes

Platform responses can include `timeSlots[]`. Publication schedules reference those IDs through
`timing.timeSlotId`.

```json
{
  "kind": "single",
  "date": "2026-01-15",
  "timing": {
    "type": "timeSlot",
    "timeSlotId": 6001
  }
}
```

:::info{title="Reference time slots by ID"}

Do not send time-slot display data in publication schedule writes. Read the slot ID from platform
configuration and send that ID.

:::

## Migration Checklist

- Choose one schedule mode per platform before creating or updating it.
- Send all seven day flags for weekly schedules.
- Send non-empty date lists for manual schedule create.
- Do not use `PUT` to switch a platform between weekly and manual modes.
- Treat manual schedule `PATCH` as an instruction list.
- Read `timeSlots[]` from platform responses before creating publication schedules that use time
  slots.