---
title: Previews and approvals
description: "How schedule-changing commands work in two steps: preview a change, review what it would do, then apply it with an approval token."
---

Some changes reach many families at once: cancelling a class date, adding a holiday to a term, or moving private lessons. Soljio does not let an integration make these changes in one call. A client first asks for a preview, which runs the whole command and then rolls it back. The response describes the effect. The client then applies the change by sending back the preview ID and an approval token.

This gives a person, or your own review logic, a chance to check the effect before it happens.

## The two steps

1. **Preview**

    Send the command's input to `POST /v0/commands/preview_{command}`. For example, to preview cancelling a class date:

    ```bash
    curl -sS -X POST "https://api.soljio.com/v0/commands/preview_cancel_session" \
      -H "Authorization: Bearer $SOLJIO_TOKEN" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: preview-cancel-session-SESSION_ID-1" \
      -d '{"session_id":"SESSION_ID","cancel_reason":"Pool closed"}'
    ```

    The response describes what would change and carries the proof you need to apply it:

    ```json
    {
      "data": {
        "approval_token": "RETURNED_APPROVAL_TOKEN",
        "changes": { "created": 0, "deleted": 0, "updated": 1 },
        "expires_at": "2026-01-05T17:19:11.000Z",
        "organization_id": "ORGANIZATION_ID",
        "preview_id": "PREVIEW_ID",
        "proposed_input": {
          "session_id": "SESSION_ID",
          "cancel_reason": "Pool closed"
        },
        "requires_approval": true
      },
      "idempotent_replay": false,
      "request_id": "00000000-0000-4000-8000-000000000003"
    }
    ```

2. **Apply**

    Send only the preview ID and the approval token to the real command:

    ```bash
    curl -sS -X POST "https://api.soljio.com/v0/commands/cancel_session" \
      -H "Authorization: Bearer $SOLJIO_TOKEN" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: apply-cancel-session-SESSION_ID-1" \
      -d '{"preview_id":"PREVIEW_ID","approval_token":"RETURNED_APPROVAL_TOKEN"}'
    ```

    The command runs exactly the input that was previewed and commits atomically.

## Which commands work this way

Eleven commands apply through a preview:

`add_term_holiday`, `cancel_private_lesson_booking`, `cancel_session`, `create_offering`, `create_private_lesson_booking`, `create_session`, `move_private_lessons`, `replace_offering_schedule`, `update_offering`, `update_recurring_schedule_rule`, and `update_session`.

For example, `cancel_session` needs `schedule.apply` to apply and `schedule.preview` to preview. `create_offering` needs `catalog.write` to apply, and `schedule.preview` plus `catalog.write` to preview.

Each has a matching `preview_{command}` operation that takes the command's normal input. The command itself takes only `preview_id` and `approval_token`. The contract's request schema for each of these commands shows exactly that.

The older fixed-date pair works the same way: `preview_offering_schedule` followed by `apply_offering_schedule`. The preview takes `offering_id`, `timezone`, and a list of `dates` (1 to 120 future dates on one day, each with a local date and local start and end times). It only appends dates; it never replaces, reschedules, or cancels them.

## Rules the API enforces

- **Scopes.** Previewing needs `schedule.preview` plus the command's own scopes other than `schedule.apply`. Applying needs the command's scopes, including any conditional ones for the input you previewed. The contract lists both sets in `x-required-scopes` and `x-scope-rules` on the preview and on the command. See [Scopes](/developers/scopes).
- **Same credential.** A preview and its approval belong to the school and the token that created them. Another token cannot apply it, and the apply request returns `404` `not_found`.
- **Same command.** The approval token only works for the command it was issued for.
- **Expiry.** An approval expires 15 minutes after the preview. An expired approval returns `409`.
- **One use.** A preview can be applied once. A second attempt returns `409`.
- **State must not change.** Apply re-reads the data the preview depended on. If it changed, the apply fails with `409` and the message `The reviewed state changed. Create a new preview.` Create a new preview and review it again.
- **Both steps need keys.** The preview and the apply are separate commands, so each needs its own `Idempotency-Key`. See [Idempotency](/developers/idempotency).
- **Nothing is saved by a preview.** The preview runs in a transaction that is rolled back, including any work it would have scheduled.
- **Retention.** Preview records are kept for 24 hours after they expire, and then deleted.

## The approval token is not a human sign-off

The approval token proves that the apply request matches a preview your token created and that the state has not changed. It does not prove that a person looked at it. If a human must approve a change, your integration has to put that review between the two steps. The contract for these commands says the same: the integration must obtain operator approval.

For agents, the MCP server marks the apply commands as requiring confirmation with the user, and lets preview tools run freely. See [Agents and MCP](/developers/agents-and-mcp).

## Troubleshooting

| Response | Cause | Fix |
| --- | --- | --- |
| `404` `not_found` on apply | The preview ID is unknown, belongs to another token, or was issued for a different command | Create a preview with the same token and apply it with the matching command |
| `409` `conflict` on apply | The approval expired, was already used, or the token is wrong | Create a new preview |
| `409` `conflict` with `The reviewed state changed` | Data changed between preview and apply | Create a new preview and review it again |
| `400` `invalid_request` on apply | The body has anything other than `preview_id` and `approval_token` | Send only those two fields |
| `403` `forbidden` | The token lacks a scope that the preview or the apply needs | Read `WWW-Authenticate` and create a token with the missing scope |
