Skip to content
Soljio Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Previews and approvals

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

Preview

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

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:

{
  "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"
}

Apply

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

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.
  • 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.
  • 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.

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

Was this page helpful?