---
title: "Change a booking"
method: POST
path: "/api/v1/modify"
---

# Change a booking

`POST /api/v1/modify`

## Request

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

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.

## Request body

- object
  - `transaction_id` string, uuid, required
  - `quote_token` string, required
  - `new_allocation_id` string, uuid
  - `idempotency_key` string, required: Unique per write request (a UUID). Retrying with the same key returns the original result.

## Response `200`

Success

- object
  - `transaction_id` string, 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_actions` string[]: The operations you may call on this job now. Anything else is refused (INVALID_STATE, ALREADY_BOOKED, ALREADY_CANCELLED).
  - `next_actions` string[]: The suggested next steps, from a fixed list.
  - `job_version` integer, 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.
  - `change` object, required: What kind of change this was (a set): capacity (the time or the cleaners), commercial (the price or anything priced: extras, skips, conditions, the home), eligibility (the home or the conditions, judged again), approval (something the owner must say yes to; refused as NEEDS_OWNER_APPROVAL), non_commercial (none of these). rechecked: what was checked again (always approval, eligibility and commercial, since the job is quoted again; capacity when the time or cleaners change).
    - `kinds` string[]
    - `rechecked` string[]
    - `price` object
      - `from` number
      - `to` number
      - `currency` string
    - `from_version` integer, nullable
    - `to_version` integer, nullable
    - `refused` 'non_commercial' | 'commercial' | 'eligibility' | 'capacity' | 'approval': On a refusal: the kind whose check said no. The booked job is unchanged.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/commontape/apis/commontape-agent-api.md) · [All operations](https://skmtc.dev/commontape/apis/commontape-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/commontape/apis/commontape-agent-api/revisions/714820e6cc4d?raw)