---
title: "Cancel"
method: POST
path: "/api/v1/cancel"
---

# Cancel

`POST /api/v1/cancel`

## Request

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

Cancels your own held, waiting (pending_approval) or booked job and releases the slot. Say why with reason (optional; left out it reads as not_given). The answer carries cancellation: by, at, reason, fee (null), policy, capacity_released. CommonTape takes no cancellation fee; any charge is between the customer and the business. Already cancelled answers ALREADY_CANCELLED (a job the business called off also carries recovery); a job a day past its window is completed first, so it answers INVALID_STATE. The owner calling off a booked job is supplier_cancelled, never this.

## Request body

- object
  - `transaction_id` string, uuid, required
  - `reason` 'customer_changed_plans' | 'customer_booked_elsewhere' | 'booked_in_error' | 'customer_other': Why, for the customer. Optional.
  - `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` 'cancelled', 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.
  - `cancellation` object, nullable, required: How the job was cancelled. null unless cancelled or supplier_cancelled. CommonTape takes no cancellation fee; any charge is between the customer and the business.
    - `by` 'agent' | 'business' | 'system': agent: you (for the customer). business: the owner called it off. system: CommonTape (the business stopped taking jobs).
    - `at` string, date-time
    - `reason` object
      - `code` 'customer_changed_plans' | 'customer_booked_elsewhere' | 'booked_in_error' | 'customer_other' | 'insufficient_staff' | 'schedule_conflict' | 'illness_or_emergency' | 'merchant_cancelled_other' | 'business_unavailable' | 'not_given'
      - `label` string
    - `from_state` string, nullable
    - `fee` unknown
    - `policy` object
      - `code` 'no_fee'
      - `text` string
    - `capacity_released` boolean: The time was given back in the same step.

## 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)