Change a booking

Commits a change to a booked job: first quote the job again with its transaction_id (the next version), then modify with that quote_token, optionally moving it to another window. The job stays booked; the old version, quote and price are kept. The answer, and every refusal, carries change: its kinds (capacity, commercial, eligibility, approval, non_commercial), what was checked again and the price from and to. A refused change leaves the booked job exactly as it was; a new time and a new price commit together or not at all. A job the business called off answers SUPPLIER_CANCELLED with recovery. Moving to a time that is too soon answers INSUFFICIENT_NOTICE with error.earliest (M-21); a job that keeps its time is never checked again against a later No. The owner is emailed once about a change they can see (a new time, price, home or request). Check the new quote's price against your customer's limit before you modify: a change is priced against the business's current offering. A quote of another job, or an older quote of this one, answers MODIFICATION_CONFLICT or QUOTE_EXPIRED. Refused with NEEDS_OWNER_APPROVAL (next_actions cancel, search) when the new quote adds, drops or rewords something the owner must approve. Refused with PRICE_MISMATCH (next_actions cancel, search) when it leaves out a task the booked job asked for: send every booked task again in inputs.addons. Refused with PRICE_MISMATCH when it is for a different ZIP, drops the home (leaves out a fact of the home the booked job stated: its kind, size or a room count; new values are allowed; refused with next_actions cancel, search), or does not state exactly the day and hour conditions of the window (a job that stays in its window keeps the same-day or next-day condition it was booked with). Also refused with NEEDS_OWNER_APPROVAL (next_actions cancel, search; booking_authority in the error) when the new version would not book on its own and costs more than the booked one, or moves a job the owner said yes to into another window: the owner's yes covered that version only.

post/api/v1/modify

Request

  • Base URL: https://commontape.com
  • URL: https://commontape.com/api/v1/modify
  • Auth: HTTP bearer

Request body

transaction_idstring uuid required
quote_tokenstring required
new_allocation_idstring uuid
idempotency_keystring required

Unique per write request (a UUID). Retrying with the same key returns the original result.

Response

Success

transaction_idstring uuid required
state'booked' required

One of ten states, each with one meaning. 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.

allowed_actionsstring[]

The operations you may call on this job now. Anything else is refused (INVALID_STATE, ALREADY_BOOKED, ALREADY_CANCELLED).

next_actionsstring[]

The suggested next steps, from a fixed list.

job_versioninteger nullable

The job's version. Every change to the job is a new version; old versions, their quotes and prices are kept, never written over.

Changes

No recorded changes to this operation across all 1 revision of this API.