Preflight check
Some changes in Zooza do more than change one field: they can move money, affect other bookings, or need a decision
first. A preflight check tests such a change before it happens. Send the request you mean to make with
?action=preflight_check added, and Zooza answers what would happen and writes nothing.
This page covers what's the same for every operation. Each operation has its own checks and properties: the reference documents them per operation, and the guides show how to use them in a real flow.
How it works
- Check: send the request with
?action=preflight_check. - Decide: read
checksto see whether the change would go through, and usepropertiesto show the user what would happen, or to ask for the decisions it needs. - Apply: send the same request without
?action=preflight_check, with the user's decisions added to the body.
The apply step checks everything again. Data can change between the two calls, so the apply runs the same checks on current data and refuses the change if one fails. Nothing links the two calls (no token, nothing stored), so a check that passed a minute ago is not a promise.
A check costs the same points as the change itself, although it writes nothing.
The answer
The answer is always a 200 with two objects:
{
"checks": {
"<check name>": { "name": "<check name>", "result": "passed", "severity": "error" }
},
"properties": {
"<property name>": { "name": "<property name>", "value": "<depends on the property>" }
}
}
checks: each check is a question about the change, with a result of passed or not_passed and a severity:
| Severity | If it didn't pass |
|---|---|
error | The change would be refused. Don't offer to apply it: explain why, or ask for what's missing. |
warning | The change would go through, but the user should confirm something first. |
notice | Something the user should know. It never blocks the change. |
properties: what you need to decide, such as the records involved, amounts, or the choices the change offers.
Each property's value has its own shape.
The status is 200 whether or not the change would go through. Read checks, not the status code. Here, a
check with severity error didn't pass:
A refused change: still a 200 (reference)
PUT /v3/registrations/168321?action=preflight_check
{
"action": "change_status",
"status": "pre_registered"
}
Answer: 200
Answer body (200)
{
"checks": {
"rules_hold": {
"name": "rules_hold",
"result": "passed",
"severity": "error"
},
"decision_missing": {
"name": "decision_missing",
"result": "passed",
"severity": "error"
},
"money_moves": {
"name": "money_moves",
"result": "passed",
"severity": "notice"
},
"transferred_money_stays": {
"name": "transferred_money_stays",
"result": "passed",
"severity": "notice"
},
"currency_conversion": {
"name": "currency_conversion",
"result": "passed",
"severity": "notice"
},
"status_allowed": {
"name": "status_allowed",
"result": "not_passed",
"severity": "error"
}
},
"properties": {
"result": {
"name": "result",
"value": {
"booking": {
"type": "registration",
"id": 168321
},
"root": {
"type": "registration",
"id": 168321
},
"limits": {
"max_depth": 3,
"truncated": false
},
"members": [
{
"type": "registration",
"id": 168321,
"summary": {
"name": "Ballet basics",
"client_name": "Anna Novak",
"course": {
"id": 990,
"name": "Kids gymnastics"
},
"schedule": {
"id": 6779,
"name": "Tuesday 17:00"
},
"product": null,
"status": "canceled",
"trial": false,
"balance": -110,
"currency": "EUR"
},
"parent": null,
"paid_by": null,
"pays_for": [],
"previous": null,
"next": null
}
],
"related": []
}
},
"transfers": {
"name": "transfers",
"value": []
},
"balances": {
"name": "balances",
"value": []
},
"refusals": {
"name": "refusals",
"value": []
},
"options": {
"name": "options",
"value": {}
}
}
}
Handling any preflight check
You can handle every operation's check with the same code, and add operation-specific handling only where you need it:
- If any check with severity
errorisnot_passed, don't offer to apply. - If any check with severity
warningisnot_passed, ask the user to confirm. - Show each
noticethat'snot_passedas information. - Read
propertiesonly for the operations your app knows, by property name. Ignore names you don't know: an operation can gain checks and properties over time.
Errors
Before it gets to checks, a preflight check can fail with the same errors as the change itself: a 422 when the
body doesn't match the schema, or a 400 when Zooza refuses the request (a missing field the change needs, for
example). See Errors.
Operations with a preflight check
| Operation | Request | What it checks |
|---|---|---|
| Update a registration | PUT /v3/registrations/{ID}?action=preflight_check | preview a change_status (send the same body as the change itself) without writing anything. Any other body action is refused. |
For a worked example, see Cancel a registration: it uses the check to find the client's make-up credits and the registrations booked together, and to ask the right question before cancelling.