scope-change

Raise a change order against a quote or work order and return its CO-YYYY-NNNN number: the reference, the client, a title, the date, and the original contract value in minor units. Free tier: 5 open.

{
  "type": "object",
  "properties": {
    "reference": {
      "type": "string",
      "maxLength": 64,
      "description": "The quote or work order this change order is against, by its id, e.g. Q-2026-0003 or WO-2026-0001"
    },
    "reference_kind": {
      "type": "string",
      "enum": [
        "quote",
        "work_order"
      ],
      "description": "What the reference is. Inferred from the id when omitted: WO-... is a work order, anything else a quote"
    },
    "client": {
      "type": "string",
      "maxLength": 200,
      "description": "The client the change is agreed with, as named on the quote or work order"
    },
    "title": {
      "type": "string",
      "maxLength": 2000,
      "description": "What the change is, in one line, e.g. Add a second landing page and drop hosting"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day the change was raised, YYYY-MM-DD. Default today"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "ISO code the contract is priced in. Defaults to the shared business profile's currency"
    },
    "original_value_minor": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000000,
      "description": "The contract value BEFORE any change order, net of VAT, in whole minor units. Required on the first change order against a reference; inherited by every later one"
    },
    "note": {
      "type": "string",
      "maxLength": 2000
    },
    "duplicate_ok": {
      "type": "boolean",
      "description": "Raise it even though an identical change order exists on this reference. Default false"
    }
  },
  "required": [
    "reference",
    "client",
    "title"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Add one line to a draft change order: added or removed with a quantity and a unit price in minor units, or changed with the old and the new quantity and price, each with a reason and a date. Free.

{
  "type": "object",
  "properties": {
    "change_order": {
      "type": "string",
      "maxLength": 200,
      "description": "The change order id, e.g. CO-2026-0001, or its title when only one carries it"
    },
    "kind": {
      "type": "string",
      "enum": [
        "added",
        "removed",
        "changed"
      ],
      "description": "added for new work, removed for work taken out, changed for a line whose quantity or price moves"
    },
    "description": {
      "type": "string",
      "maxLength": 2000,
      "description": "The line as it reads on the quote or work order, e.g. Website audit"
    },
    "quantity": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1000000,
      "description": "added or removed: how many. changed: the NEW quantity"
    },
    "unit_price_minor": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000000,
      "description": "added or removed: the unit price in whole minor units. changed: the NEW unit price. 45000 is EUR 450.00"
    },
    "was_quantity": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1000000,
      "description": "changed only: the quantity before the change"
    },
    "was_unit_price_minor": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000000,
      "description": "changed only: the unit price before the change, in whole minor units"
    },
    "reason": {
      "type": "string",
      "maxLength": 2000,
      "description": "Why, in the client's words if you have them, e.g. Client asked for a second page after the kickoff"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day the change was asked for, YYYY-MM-DD. Default the change order's date"
    },
    "tax_rate": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000,
      "description": "VAT percent for this line, overriding the shared profile's default"
    },
    "note": {
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": [
    "change_order",
    "kind",
    "description",
    "quantity",
    "unit_price_minor",
    "reason"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Move one change order along and stamp the date and note: draft to sent, sent to approved or rejected, either to void. Backwards steps, an unsent approval and a backdated move are all refused.

{
  "type": "object",
  "properties": {
    "change_order": {
      "type": "string",
      "maxLength": 200,
      "description": "The change order id, e.g. CO-2026-0001, or its title when only one carries it"
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "sent",
        "approved",
        "rejected",
        "void"
      ],
      "description": "The status to move to"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day it happened, YYYY-MM-DD. Default today"
    },
    "note": {
      "type": "string",
      "maxLength": 2000,
      "description": "What happened, e.g. Emailed to the client, or Approved by phone, confirmed in writing"
    }
  },
  "required": [
    "change_order",
    "status"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return one change order in full by CO number or client: every added, removed and changed line with its reason and delta, VAT, delta gross, the status history and the running value. change_order_list finds the id.

{
  "type": "object",
  "properties": {
    "change_order": {
      "type": "string",
      "maxLength": 200,
      "description": "The change order id, e.g. CO-2026-0001, or its title when only one carries it"
    }
  },
  "required": [
    "change_order"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List change orders newest first with status, reference, client, currency and net delta, and above them the APPROVED and the pending delta per currency, kept apart. Filter by reference, status, client, date.

{
  "type": "object",
  "properties": {
    "reference": {
      "type": "string",
      "maxLength": 64,
      "description": "Only change orders against this quote or work order"
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "sent",
        "approved",
        "rejected",
        "void",
        "open"
      ],
      "description": "One status, or open for draft and sent together"
    },
    "client": {
      "type": "string",
      "maxLength": 200,
      "description": "Only change orders whose client name contains this text"
    },
    "from": {
      "type": "string",
      "maxLength": 10,
      "description": "Earliest date, YYYY-MM-DD"
    },
    "to": {
      "type": "string",
      "maxLength": 10,
      "description": "Latest date, YYYY-MM-DD"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "Maximum rows returned, default and ceiling 500"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Delete a DRAFT change order with no lines, freeing an open slot. One sent, approved, rejected or voided is refused, and so is one carrying lines: void it with change_order_status instead. The number is not reissued.

{
  "type": "object",
  "properties": {
    "change_order": {
      "type": "string",
      "maxLength": 200,
      "description": "The change order id, e.g. CO-2026-0001, or its title when only one carries it"
    }
  },
  "required": [
    "change_order"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The running value of one quote or work order: original, approved deltas and current value, with pending draft and sent deltas kept apart. Net of VAT. A reference with no change order is refused.

{
  "type": "object",
  "properties": {
    "reference": {
      "type": "string",
      "maxLength": 64,
      "description": "The quote or work order this change order is against, by its id, e.g. Q-2026-0003 or WO-2026-0001"
    }
  },
  "required": [
    "reference"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Render one change order as a plain-text document for the client to approve: every line with its reason, the delta net and gross, the contract value before and after, and an approval block. The same text also comes back as a .txt download link valid for one hour. Pro.

{
  "type": "object",
  "properties": {
    "change_order": {
      "type": "string",
      "maxLength": 200,
      "description": "The change order id, e.g. CO-2026-0001, or its title when only one carries it"
    }
  },
  "required": [
    "change_order"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Build the approved delta as invoice_create-ready items in MAJOR units and quote_create-ready items in MINOR units, with VAT at the shared profile rate. Writes nothing and creates nothing. Pro.

{
  "type": "object",
  "properties": {
    "change_order": {
      "type": "string",
      "maxLength": 200,
      "description": "The change order id, e.g. CO-2026-0001, or its title when only one carries it"
    },
    "issue_date": {
      "type": "string",
      "maxLength": 10,
      "description": "The invoice issue date, YYYY-MM-DD. Default today"
    },
    "tax_rate": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000,
      "description": "VAT percent for lines with no rate of their own, overriding the shared business profile's default"
    }
  },
  "required": [
    "change_order"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Report this endpoint's licence state for your token as JSON: the product, the tier free or pro, why it is not Pro, and the checkout URL. Call it to explain a free-tier refusal. No arguments, nothing changes.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Turn Pro on for this connection with key, an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. Data under your token stays; a wrong or expired key changes nothing. license_status confirms it.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "License key from checkout, MCPL1.<payload>.<signature>"
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}