Admin Booking Lifecycle

Admin-specific booking operations: status changes, check-in/out, and document generation. For customer booking management, see Customer Booking Lifecycle. For creating bookings, see Admin Booking Creation. For general conventions, see JSON-API Conventions.

Prerequisites

A valid Bearer token with admin access — see Authentication
Organization context (?o={organization_id})

Status Changes

Request path documentation:

paths/admin/bookings.yaml for PATCH /api/v1/bookings/{booking_id}
paths/admin/bookings.yaml for GET /api/v1/bookings/{booking_id}/cancel

Accept a Requested Booking

When a booking has status requested, accept it by updating the booking status:

PATCH /api/v1/bookings/{booking_id}?o={org_id}

Example payload:

{
	"data": {
		"id": "{booking_id}",
		"type": "bookings",
		"attributes": {
			"status": "accepted"
		}
	}
}

Reject a Requested Booking

Reject a requested booking with the same update endpoint:

PATCH /api/v1/bookings/{booking_id}?o={org_id}

Example payload:

{
	"data": {
		"id": "{booking_id}",
		"type": "bookings",
		"attributes": {
			"status": "rejected"
		}
	}
}

Cancel a Booking

Cancel an accepted or requested booking with the dedicated cancel action:

GET /api/v1/bookings/{booking_id}/cancel?o={org_id}

This runs the booking cancellation flow. Refunds and invoice adjustments follow the configured cancellation policy.

Check-In / Check-Out

Request path documentation:

paths/admin/bookings.yaml for POST /api/v1/bookings/{booking_id}/check-in
paths/admin/bookings.yaml for POST /api/v1/bookings/{booking_id}/check-out
Scan for POST /api/v1/scans (staff / kiosk scanner)

Record customer arrivals and departures.

Check-In

POST /api/v1/bookings/{booking_id}/check-in?o={org_id}
X-Supports-Dynamic-Form: true

Optional body fields:

Field	Type	Description
`latitude` / `longitude`	number	Required when the resource uses geo check-in
`form_data`	object	Submitted after collecting delayed check-in details (see below)
`send_notification`	boolean	Defaults to `true`

Check-Out

POST /api/v1/bookings/{booking_id}/check-out?o={org_id}

Both endpoints:

Log a Scan record with the timestamp
Update the booking’s check-in/check-out status
Can be triggered by admin users or via self-service terminals

Resources can be configured with auto-expiry — if a customer doesn’t check in within a configured window, the booking expires automatically.

Delayed forms at check-in

Legal documents and custom forms can be configured with collection timing check_in. If those details are still missing when you check a booking in, the API does not complete the check-in until the client collects and submits them. Advertise support for the dynamic check-in form with:

X-Supports-Dynamic-Form: true

Without that header (and without form_data), check-in fails with HTTP 400 and code scans.check_in_requires_details_unsupported. 1. First attempt — details still required:

{
  "meta": {
    "status": "requires_details",
    "form_url": "https://…/api/ui/booking-check-in-form?booking={id}&access_token=…"
  },
  "data": {
    "type": "bookings",
    "id": "{booking_id}",
    "attributes": {
      "check_in_date": null
    }
  }
}

2. Load the form from meta.form_url (GET /api/ui/booking-check-in-form). It returns the same dynamic-form shape as checkout (components, validations), limited to still-missing items (documents.{uuid}, service_custom_fields.{uuid}). 3. Re-submit check-in with the collected values:

POST /api/v1/bookings/{booking_id}/check-in?o={org_id}
X-Supports-Dynamic-Form: true

{
  "form_data": {
    "documents": {
      "{document_uuid}": { "accepted": true, "send_copy": false }
    },
    "service_custom_fields": {
      "{field_uuid}": "value"
    }
  }
}

On success, meta.status is the resulting scan status (for example valid) and check_in_date is set. Invalid form_data returns HTTP 422. Timing / geo / business-rule failures return HTTP 400 with a scans.* error code.

Scanner endpoint (`POST /scans`)

Staff and kiosk clients that create scans by booking code use the same delayed-form flow. Unlike the booking check-in action, submit details only as data.attributes.meta.form_data (JSON:API) — top-level form_data is ignored.

POST /api/v1/scans?o={org_id}&code={booking_code}&scannable_type=bookings
X-Supports-Dynamic-Form: true

{
  "data": {
    "type": "scans",
    "attributes": {
      "scan_type": "check_in"
    }
  }
}

Situation	Result
Header present, no `meta.form_data`, details pending	Scan is created with `data.attributes.status: "requires_details"` and `data.attributes.meta.form_url`; booking is not checked in
Header missing, no `meta.form_data`, details pending	HTTP 400, `scans.check_in_requires_details_unsupported`
`data.attributes.meta.form_data` provided (and valid)	Details are persisted, scan resolves to `valid`, booking `check_in_date` is set

POST /api/v1/scans?o={org_id}&code={booking_code}&scannable_type=bookings
X-Supports-Dynamic-Form: true

{
  "data": {
    "type": "scans",
    "attributes": {
      "scan_type": "check_in",
      "meta": {
        "form_data": {
          "documents": {
            "{document_uuid}": { "accepted": true, "send_copy": false }
          },
          "service_custom_fields": {
            "{field_uuid}": "value"
          }
        }
      }
    }
  }
}

See Scan for the resource schema and create parameters.

Generating Documents

Generate a PDF or ticket from a document template:

GET /api/v1/bookings/{booking_id}/generate-file/{template_id}?o={org_id}

Parameter	Description
`template_id`	UUID of the document template to use
`override` (query)	`true` to regenerate if a file already exists

Returns a files resource with the generated document.

Booking exports are documented with the other admin export endpoints in Exports.

Common Errors

Error	Cause	Solution
`403` — unauthorized	Insufficient admin permissions	Verify role has booking management permission
`422` — already checked in	Duplicate check-in attempt	Check booking status before check-in
`400` — `scans.check_in_requires_details_unsupported`	Delayed check-in details are required but the client did not send `X-Supports-Dynamic-Form: true` (and no `form_data`)	Send the capability header, load `form_url`, then re-submit with `form_data`
`422` — invalid `form_data`	Missing required signature or custom field	Fix validation errors from the check-in form and retry
`404` — template not found	Invalid document template UUID	Verify template exists in the organization

​Prerequisites

​Status Changes

​Accept a Requested Booking

​Reject a Requested Booking

​Cancel a Booking

​Check-In / Check-Out

​Check-In

​Check-Out

​Delayed forms at check-in

​Scanner endpoint (POST /scans)

​Generating Documents

​Common Errors

Prerequisites

Status Changes

Accept a Requested Booking

Reject a Requested Booking

Cancel a Booking

Check-In / Check-Out

Check-In

Check-Out

Delayed forms at check-in

Scanner endpoint (`POST /scans`)

Generating Documents

Common Errors