Employee batches and a single seat checkout
Create or reactivate up to 100 employees with one durable operation and a reviewed seat quote.
A batch contains 1 to 100 specific employees. Choose either creation or reactivation; do not mix the two. Preparing a batch does not create employees, send invitations or charge your card. CSV and Excel imports are outside this flow.
Availability
Employee batches may not be enabled for your account. Check purchase_availability.employee_batches: the existing authenticated application endpoint GET /api/features publishes it in data.purchase_availability as a server boolean, together with customer_offers. When it is off or unknown, treat batches as not enabled.
- Not enabled:
POST /v1/employeesandPOST /v1/employees/{employee}/reactivatekeep the synchronous per-employee seat charge described in Employee seat billing. - Enabled: those two operations use the same reliable seat quote as batches and can return
503 employee_batch_quote_unavailablewhen it cannot be obtained. Nobody was created or charged: retry the same request.
During an active trial, employees are added at no charge. When the company starts paying, the employees created during the trial become inactive without any automatic charge, and reactivating each one, individually or in a reactivation batch, charges its seat. See Employees created during the trial.
Prepare and review
Use POST /v1/employee-batches with employees:write and an Idempotency-Key. Keep a stable row_id for each person. Creation sends a profile; reactivation sends the existing employee's UUID as employee_id. No company or price can be selected in the body: the authenticated company owns the operation.
{
"kind": "reactivate",
"items": [
{"row_id": "row-1", "employee_id": "019c0c2f-b018-7ddf-8c70-546c61c7af1f"}
]
}The response has data.id (UUID), quote_version, status, quote and allowed_actions. Review the amount due today and the recurring monthly total. Covered employees and reusable paid seats are counted separately from chargeable seats. Amounts are integer EUR cents; null means unknown, never free. A quote without reliable billing data cannot authorize a purchase.
Creation validates names, email, employment type, hours, region and hire date; optional external identifiers must remain unique in the company. A repeated employee, invalid row, active employee selected for reactivation, plan cap or another seat operation blocks the whole batch. Row validation returns details.row_errors with row_id, field and message; ordinary HTTP field validation can also return indexed errors.
Confirm and recover
Send POST /v1/employee-batches/{id}/confirm with the reviewed quote_version and a new stable key for that confirmation intent. Respect allowed_actions. A changed or expired quote requires POST /v1/employee-batches/{id}/quote, with the previous version and its own key, and another review before confirming.
A confirmation can return 202 while payment or employee settlement is pending. Keep the operation UUID and use GET /v1/employee-batches/{id}; do not create another batch to retry. An allowed action_url can require card authentication. A payment-method error can include a verified details.payment_setup_url. After returning, read the operation and refresh its quote when required.
| Result | What to do |
|---|---|
completed | Read the resulting employee UUIDs in result. |
processing, requires_action, payment_pending, paid | Read the same operation until settlement is known. |
compensating, needs_review | Keep the receipt and wait for recovery; do not repeat the purchase. |
failed, cancelled, compensated | Read the final receipt before deciding whether to start a new operation. |
POST /v1/employee-batches/{id}/cancel only requests an action currently allowed by the server. After a financial attempt, cancellation may need verified restoration or a refund; it is not a promise of an immediate reversal. List your operations with GET /v1/employee-batches (employees:read), using cursor, limit and optional statuses[].
Application and MCP
In the application, open the employee list's batch action, enter profiles or select inactive employees, then review the checkout on its dedicated page. Closing or reloading a pending checkout preserves the server operation. If employee access is later lost, Billing exposes only a minimal receipt and an allowed cancellation; it does not authorize another charge or card authentication for the inaccessible product.
The equivalent MCP tools are prepare_employee_batch, refresh_employee_batch_quote, confirm_employee_batch, cancel_employee_batch, get_employee_batch and list_employee_batches. Writes take idempotency_key; confirmation and cancellation can have financial effects. Module, plan, membership and sandbox restrictions still apply in REST and MCP. A sandbox cannot make a real purchase.