> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kordless.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Holds, booking, and deposits
> How provisional holds, deposits, and external handoffs work when a customer accepts an offer.
A commitment records the boundary event with one of three supporting mechanics: a provisional hold, a deposit, or an external handoff. Each mechanic crosses the boundary differently, and the Commitments page shows which one is in play.
## Before you start
* A workspace with an active Live environment and the booking capability enabled
* A quote in the **quoted** state — an approved offer the customer has accepted
* Access to create commitments for this workspace
Commitments can only be created from a `quoted` quote. A quote in `awaiting_approval` is not commitment material — the offer has not been sent to the customer yet.
## Creating a commitment
When a customer accepts a quoted offer, the owner creates a commitment from the Quotes work list. The **Create commitment** action appears on quoted quotes.
The owner provides:
* **Deposit amount (optional)** — A dollar amount. When provided, Kordless generates a Stripe checkout link for the customer. The deposit is not charged until the customer completes checkout.
* **Hold hours (optional)** — A duration in hours. When provided, the hold expires automatically after this period if not confirmed.
Both fields are optional. A commitment can be created with a deposit and a hold, with only one, or with neither.
## Holds
A held commitment is a provisional hold — it records that the customer accepted the offer, but nothing is secured yet. The boundary summary on the Commitments page shows:
| Condition | What the page shows |
| --------------------- | ---------------------------- |
| Hold with a deadline | "Hold until \[date] \[time]" |
| Hold with no deadline | "Held (no deadline)" |
A held commitment is never a firm booking. It records acceptance and an optional deadline. The customer's slot is not reserved until the commitment is confirmed through a deposit or an external handoff.
### Hold expiry
When a hold duration is set, the hold expires automatically after that period. An expiry sweep moves lapsed holds from `held` to `expired`. Once expired, the commitment status becomes **released**.
If no hold duration is set, the hold does not auto-expire. The owner must release it manually.
## Deposits
When a deposit amount is provided at commitment creation, Kordless generates a Stripe checkout session. The session is created through an outbox effect keyed on the commitment ID — a retry can never mint a second session.
### Deposit states
| State | What it means | What the page shows |
| -------- | ------------------------------------------------------------------ | ---------------------------- |
| Pending | The checkout link has been generated but the customer has not paid | "Deposit link →" (clickable) |
| Paid | The customer completed checkout | "Paid \$X" |
| Refunded | The deposit was refunded | "Refunded \$X" |
### What happens when a deposit is paid
When the customer completes the Stripe checkout:
1. The webhook confirms the deposit payment.
2. The commitment moves from `held` to `confirmed` in the same transaction as the deposit record.
3. The commitment status becomes **deposit paid**.
4. A redelivered webhook confirms nothing twice — the transaction is idempotent.
The quote state also moves to `deposited` at this point.
## Booking and external handoff
When the boundary is crossed without a Kordless deposit — for example, the business records the booking in its own system — the owner confirms the commitment with an external reference.
The **confirm commitment** action records an external booking or order reference. The commitment moves from `held` to `confirmed`, and the boundary summary shows "Handed off · \[reference]".
This is how Kordless hands off to downstream operating systems. The external reference is the bridge — it tells you where to look for the booking in your own tools.
## Confirmed is terminal
Once a commitment is confirmed — whether through a deposit or a handoff — it is terminal at this boundary. There is no "unconfirm" action. What happens after confirmation belongs to your operating systems.
If a deposit is refunded after confirmation, the commitment status becomes **released** and the deposit cell shows "Refunded \$X". The commitment record itself remains `confirmed` — the refund is a post-boundary fact.
## Idempotency
One commitment exists per quote. Creating a commitment from the same quote twice returns the existing record and emits nothing. This is a structural guarantee — the unique constraint on `(quote_id)` prevents duplicates at the database level.
## Role requirements
Creating and confirming commitments requires access to the booking capability. Members can view the Commitments page but may not see the create or release actions. If you see a permission message, ask a workspace administrator to complete this step or grant you the necessary role.
## If it does not work
If the page shows "Commitments aren't set up," the workspace has not enabled the booking capability yet. An administrator must enable booking and deposit before commitments can be created.
If the page shows that commitments aren't part of the current plan, the workspace's subscription does not include the booking capability. Contact support or upgrade the plan.
If the workspace's subscription is not active, commitments are paused. Offers and history are preserved. Resume the subscription to commit again.
The **Create commitment** action appears only on quotes in the `quoted` state. If the quote is held for review, approve or decline it first. If the quote has expired, it cannot be committed.
## Next
What happens when a commitment expires, is released, or is handed off.
What Kordless handles and what happens after commitment.