book
Commit a hold with the customer's details. Returns booked, or pending_approval (the owner must say yes: the quote's booking_authority was approval_required, or the owner's booking setting tightened since; the time stays reserved; poll status until decide_by, about once a minute: the owner has up to 2 hours, never later than an hour before the job (a job starting within about an hour keeps its hold's time); jobs waiting count toward your open holds; with no answer by then the job is expired: the job ends and the reserved time is released; you may cancel while waiting), declined (with the owner's reason, its canonical code, next_actions and next_available) or expired. Booking an already booked job answers ALREADY_BOOKED. A declined or expired answer carries alternatives and if_changed (businesses one change away: never bookable from the item; ask the customer, then search again without change.word). Every answer carries state (one of quote_incomplete, quoted, held, pending_approval, booked, completed, declined, cancelled, supplier_cancelled, expired), allowed_actions and next_actions; every error carries a code and next_actions. quote_incomplete: Not priced yet: the job needs more facts. needs says which. Nothing is held. Allowed: quote. quoted: An exact price for one exact job version, until expires_at. Nothing is held: the time is not reserved yet. Allowed: hold, quote. held: A time is reserved for this job until hold_expires_at. Book it, or cancel to let it go. Allowed: book, cancel. pending_approval: Asked to book; the owner must say yes by approval.deadline. The time stays reserved while waiting. No answer by then and the job expires and the time is released. Allowed: status, cancel. booked: The owner is committed to do this job at this price and time. Allowed: status, quote, modify, cancel. completed: The job was done. completion.source says who marked it: the owner (merchant) or CommonTape after the window ended (system). Allowed: status. declined: The owner said no. decline.reason says why; decline.next_available is the next open time when there is one. Allowed: status, quote. cancelled: Called off by the agent. The time was released. Allowed: status, quote. supplier_cancelled: Called off by the owner after it was booked. The job can be quoted again elsewhere from job. Allowed: status, quote. expired: Ran out of time: the quote passed expires_at, or the hold or the owner's answer passed its deadline. The time was released. Allowed: status, quote.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| customer | Yes | ||
| transaction_id | Yes | transaction_id from quote or hold | |
| idempotency_key | Yes | Unique per write request (a UUID). Retrying with the same key returns the original result. |