Admin UI Forms

This guide documents the internal Admin UI form endpoints used to build and apply dynamic order completion forms. Use this flow when the frontend should render backend-driven form components (customer, address, custom fields, participants) instead of hardcoding field definitions.

Endpoints

POST /api/v1/ui/admin/checkout-form
POST /api/v1/ui/admin/checkout-form/apply
POST /api/v1/ui/admin/customer-form
POST /api/v1/ui/admin/address-form
POST /api/v1/ui/admin/order-form
POST /api/v1/ui/admin/booking-form

All endpoints require:

Authorization: Bearer {token}
?o={organization_id}

Recommended Order Completion Flow

Build a checkout form from booking context.
Render returned components and collect user input.
Apply form data to booking config.
Send enriched payload to POST /api/v1/orders/from-config.

Build checkout form

POST /api/v1/ui/admin/checkout-form?o={organization_id}
Content-Type: application/json
Authorization: Bearer {token}

{
  "booking_config": {
    "order_customer_id": null,
    "bookings": [
      {
        "customer_id": null,
        "service_id": { "{service_id}": 1 },
        "resource_id": "{resource_id}",
        "start_date": "2026-04-15T09:00:00+02:00",
        "end_date": "2026-04-15T10:00:00+02:00"
      },
      {
        "customer_id": "{optional_existing_customer_id}",
        "service_id": { "{service_id}": 1 },
        "resource_id": "{resource_id}",
        "start_date": "2026-04-15T10:00:00+02:00",
        "end_date": "2026-04-15T11:00:00+02:00"
      }
    ]
  }
}

The response contains form metadata such as components, validations, default, and submitAction.The booking_config supports mixed product orders: besides bookings it accepts standalone add_ons ([{ "add_on_id": 1, "quantity": 2 }]) and booking_passes purchased from bundles ([{ "booking_bundle_id": 12, "quantity": 1 }]). At least one of the three product arrays must be present — bookings may be omitted for bundle/add-on-only orders:

{
  "booking_config": {
    "order_customer_id": "1701",
    "booking_passes": [
      { "booking_bundle_id": 12, "quantity": 1 }
    ]
  }
}

Apply submitted form data

POST /api/v1/ui/admin/checkout-form/apply?o={organization_id}
Content-Type: application/json
Authorization: Bearer {token}

{
  "form_data": {
    "customer": {
      "email": "newcustomer@example.com",
      "given_name": "Test",
      "family_name": "Customer"
    },
    "bookings_data": {
      "b_205": {
        "service_custom_fields": {
          "{booking_field_uuid}": "Wheelchair access"
        },
        "participants": [
          {
            "email": "participant@example.com",
            "given_name": "Alex",
            "family_name": "Example"
          }
        ]
      }
    }
  },
  "booking_config": {
    "bookings": [
      {
        "_booking_id": 205,
        "resource_id": "{resource_id}",
        "service_id": { "{service_id}": 1 },
        "start_date": "2026-04-15T09:00:00+02:00",
        "end_date": "2026-04-15T10:00:00+02:00"
      }
    ]
  }
}

The response includes an enriched config with resolved customer IDs and mapped custom fields. Additional config keys such as add_ons and booking_passes are passed through unchanged, so the result can be sent directly to POST /api/v1/orders/from-config for mixed product orders too.

Complete order

Use the enriched payload from step 2 as request body for:

POST /api/v1/orders/from-config?o={organization_id}

See the public admin guide for full order payload options and error handling.

Standalone Form Endpoints

Use these endpoints when editing existing entities outside the full checkout-form flow.

Customer Form

POST /api/v1/ui/admin/customer-form?o={organization_id}

{
  "customer_id": "{customer_id}",
  "address_id": "{address_id}",
  "include_address_form": true
}

customer_id is optional.
address_id is optional and can be used to prefill address values directly.
include_address_form is optional (true by default). Set to false to return customer fields without embedding address fields.
Returns customer fields and (by default) address fields with defaults if customer/address exists.

Customer form payload is split into three write namespaces:

customer.* for customer resource attributes such as given_name, family_name, email, mobile, phone, company, sex, and birth_date
address.* for address resource attributes such as street_address, zip_code, city, and country_code
custom_entry_map.{field_uuid}.value for customer custom fields in the same shape accepted by PATCH /api/v1/customers/{customer_id}

Persistence rules:

Send customer.* as customer attributes to POST or PATCH /api/v1/customers.
Forward custom_entry_map.* directly as the customer resource’s custom_entry_map attribute.
Persist address.* through the separate addresses resource, linked to the customer via relationships.addressable.

Typical update flow for an existing customer:

PATCH /api/v1/customers/{customer_id} with attributes built from customer.* plus custom_entry_map
PATCH /api/v1/addresses/{address_id} if the customer already has an address
Or POST /api/v1/addresses with relationships.addressable = customers/{customer_id} if the customer has no address yet

Address Form

POST /api/v1/ui/admin/address-form?o={organization_id}

{
  "customer_id": "{customer_id}",
  "address_id": "{address_id}"
}

customer_id is optional.
address_id is optional and takes precedence for prefilling over customer_id.
Returns address-only components prefilled from the selected address (or from the customer’s latest address if only customer_id is provided).
Address field keys use address.*.
Persist the submitted values through the addresses resource, linked via relationships.addressable when creating a new customer address.

Order Form

POST /api/v1/ui/admin/order-form?o={organization_id}

{
  "order_id": "{order_id}"
}

order_id is required.
Returns order-level custom field components prefilled from the order.
Custom field inputs use custom_entry_map.{field_uuid}.value, so they can be forwarded directly into the order resource’s custom_entry_map attribute on update.

Booking Form

POST /api/v1/ui/admin/booking-form?o={organization_id}

{
  "booking_id": "{booking_id}"
}

booking_id is required.
Returns booking-level custom field components prefilled from the booking.
Custom field inputs use custom_entry_map.{field_uuid}.value.
Persist submitted values with POST /api/v1/ui/admin/booking-form/apply (booking_id + form_data). The apply action writes filled entries, deletes cleared ("" / null) entries, and returns the booking plus a rebuilt meta.form_default.
You can also forward custom_entry_map directly into the booking resource on PATCH /api/v1/bookings/{booking_id}.
Use this during Admin Booking Edit when changing booking-specific metadata, or during order completion before creating or updating an order.

Error Handling Notes

422 for validation issues (missing required fields, malformed payload).
404 when customer_id, order_id, or booking_id does not belong to the active organization.
401 or 403 when auth or permissions are missing.

Guides

Customer API

Admin API

Data models

Identity API

Admin UI Forms

Endpoints

Recommended Order Completion Flow

Standalone Form Endpoints

Customer Form

Address Form

Order Form

Booking Form

Error Handling Notes

​Endpoints

​Recommended Order Completion Flow

​Standalone Form Endpoints

​Customer Form

​Address Form

​Order Form

​Booking Form

​Error Handling Notes

Endpoints

Recommended Order Completion Flow

Standalone Form Endpoints

Customer Form

Address Form

Order Form

Booking Form

Error Handling Notes