Cancel a job and outstanding visits

POST/api/v1/jobs/{id}/cancel

Needs an API key, and runs with the access of the member who made the key.
Send an Idempotency-Key. The same key with the same request within 24 hours gives the first answer again and changes nothing.
A connected AI assistant can use it too, as cancelJob.

Parameters

In the address

idstring (uuid)required

Headers

Idempotency-Keystringrequired
Unique user-scoped key for safely retrying this mutation for 24 hours.
At least 1 character. Up to 200 characters.

Request body

Sent as application/json.

lock_versioninteger
At least 0.

Responses

200Job details.

dataobjectrequired
Fields(24)
- lock_versionintegerrequired
  At least 0.
- created_atstring (date-time)required
- updated_atstring (date-time)required
- idstring (uuid)required
- account_idstring (uuid)required
- customer_idstring (uuid)required
- property_idstring (uuid) or null
- source_quote_idstring (uuid) or null
- numberstringrequired
- titlestringrequired
- descriptionstring or null
- statusstringrequired
  One of: active, completed, cancelled.
- billingstringrequired
  `on_completion`: one invoice once the job is complete. `per_visit`: job lines are the price of one visit, and the job is invoiced batch by batch as visits are completed while it stays active. `none`: "Don’t invoice", for work paid another way or done for free; the job is never invoiced. `monthly`: "At month end". Priced and invoiced exactly as `per_visit` is, but its completed visits are meant to wait until their month is over: a visit is due for invoicing once the day it was booked for is before the first day of the current month, in the account's time zone. createMonthEndInvoices invoices every such job at once.
  One of: on_completion, per_visit, none, monthly. Default: "on_completion".
- currencystringrequired
- subtotal_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- discount_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- tax_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- total_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- internal_notesstring or null
- completed_atstring (date-time) or null
- cancelled_atstring (date-time) or null
- archived_atstring (date-time) or null
- itemsarray of objectrequired
  Each item(12)
  idstring (uuid)required
  service_idstring (uuid) or null
  positionintegerrequired
  descriptionstringrequired
  quantitystringrequired
  Matches ^\d{1,9}(\.\d{1,3})?$.
  unit_namestring or null
  unit_price_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
  tax_rate_basis_pointsintegerrequired
  At least 0. At most 10000.
  tax_inclusivebooleanrequired
  subtotal_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
  tax_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
  total_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- repeatsarray of object
  The repeating visits still running on this job, oldest first: every series with dates left to book. A series for part of the year is listed between its seasons, when the job has no visit booked. A series whose every date is booked is not listed; its visits still carry it.
  Each item(8)
  idstring (uuid)required
  intervalintegerrequired
  At least 1. At most 99.
  unitstringrequired
  `weekday` is Monday to Friday, one visit per working day, and needs an interval of 1.
  One of: day, weekday, week, month.
  starts_onstring (date)required
  ends_onstring (date) or null
  season_from_monthinteger or null
  `season_from_month` and `season_to_month` are the first and last month of the part of the year a series runs in, 1 for January to 12 for December, both included. Give both or neither. A season may run over the year end: 11 and 2 is November to February. Dates outside it are skipped; the rhythm is not restarted.
  At least 1. At most 12.
  season_to_monthinteger or null
  `season_from_month` and `season_to_month` are the first and last month of the part of the year a series runs in, 1 for January to 12 for December, both included. Give both or neither. A season may run over the year end: 11 and 2 is November to February. Dates outside it are skipped; the rhythm is not restarted.
  At least 1. At most 12.
  lock_versionintegerrequired
  At least 0.

A refusal answers in the one error shape every operation shares.

Example

A request our own tests send. The ids are made up: put your own in their place.

curl -X POST "https://app.tradesender.co.uk/api/v1/jobs/a61b26e9-1f30-5477-8902-db1d7ecc942a/cancel" \
  -H "Authorization: Bearer $TRADESENDER_KEY" \
  -H "Idempotency-Key: $(uuidgen)"