Scheduling

Scheduling is how a change happens later. A plan version going live at midnight, a pause from the first of next month, a cancellation on a set date: all of them are recorded now and applied then.

Kontier holds these as changes, in one list (GET /v1/changes), so "what is about to happen to this customer" is a question with an answer.

✕

Why not just edit it later

Because somebody has to remember, and because the change must be visible before it happens.

A scheduled change is visible in advance: the customer's next bill can be explained before it is issued, support can see what is queued, and a mistake can be cancelled rather than reversed after the fact.

What can be scheduled

GET /v1/changes/operations lists the operations this deployment can schedule, each with the subject kinds it acts on, the when kinds it accepts (whens), its payload_schema and whether it is reversible. The operations are:

None of them is reversible: once a change has applied, undoing it is a new change, not a rollback.

When it happens

Every change carries a when. All operations above accept two kinds:

The Change object's when can name other kinds (period_end, phase_change, term_end, after_notice). Always read an operation's whens from GET /v1/changes/operations before offering a kind. A kind the operation does not accept answers WHEN_NOT_ACCEPTED. GET /v1/changes/anchors?subject=subscription:… tells you which anchored kinds one particular subject has no moment for.

Schedule one

Pause a subscription from 1 December, Berlin time
curl -X POST https://api.kontier.eu/v1/changes \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "operation":  "subscription.set_status",
    "subject_id": "8f14e45f-ceea-467a-9a1b-0f2f1a1f0f01",
    "when":       "at",
    "at":         "2026-12-01T00:00:00Z",
    "zone":       "Europe/Berlin",
    "payload": {
      "subscription_id": "8f14e45f-ceea-467a-9a1b-0f2f1a1f0f01",
      "kind":            "pause",
      "reason":          "Seasonal closure"
    }
  }'

The response is the Change, status: "planned", with the instant it resolves to in resolved_at. Its title_key and title_args say in words what will happen, for display.

Two optional fields widen or hold a change:

• "gate": "approval" holds it until a second person releases it. Releasing it happens in the dashboard; there is no API for it. You can read the approvals queue with GET /v1/approvals (see Approvals).
• "scope": "selector" with an audience_id acts on everyone in a saved audience reached through the subject ("everyone in this audience who is on plan A"). The audience is resolved again when the change fires.

Two changes of the same conflict class (see conflict_class on GET /v1/changes/operations) cannot hold the same subject at the same instant: the second answers 409 CHANGE_CONFLICT. A gate or scope this deployment or operation cannot carry out answers 501 (CHANGE_GATE_NOT_SUPPORTED, CHANGE_SCOPE_NOT_SUPPORTED).

Preview before and after

Both return who is affected, who is excluded and why, what follows downstream, and the money delta by currency.

Find what is scheduled

GET /v1/changes lists every change, newest instant first. Useful filters:

GET /v1/changes/{id} reads one.

Status

Change one

Move it to 1 January
curl -X PATCH https://api.kontier.eu/v1/changes/{id} \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "when": "at", "at": "2027-01-01T00:00:00Z", "zone": "Europe/Berlin" }'

Cancel it
curl -X DELETE https://api.kontier.eu/v1/changes/{id} \
  -H "Authorization: Bearer sk_test_…"

PATCH moves only the time. To change what a change does, cancel it and schedule a new one. Both answer 409 CHANGE_NOT_EDITABLE once a change is running or retired.

What happened

GET /v1/changes/{id}/outcomes is the record, written when the change fires: counts of applied, skipped and excluded, and one row per subject in targets with its outcome and, for skipped or excluded rows, a reason. It is empty until the change fires, because outcomes record what happened rather than predict it. For a cohort, skipped is a success: that subject already had the result.

Where scheduling shows up

1. Plan versions publish through it. catalog.publish_version with when: "at" is a scheduled release, listed on the plan under scheduled_versions.
2. Subscriptions change later through it: pause, resume or stop on a date, or a line rewrite from an instant on. Pausing or cancelling right now has its own calls on the subscription.
3. Tax rules and rate tables publish dated versions the same way.

Reference