retainer

Record a security or retainer deposit received from a client, in minor units, with its currency, the date it arrived and the bank reference. Returns the DEP-YYYY-NNNN id.

{
  "type": "object",
  "properties": {
    "client": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Client name or client id. A name the invoice server already knows brings its address, email and VAT id onto the deposit"
    },
    "amount_minor": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 1000000000000,
      "description": "What was received, in MINOR units: 50000 = 500.00 EUR, 50000 = JPY 50000. Never a decimal"
    },
    "kind": {
      "type": "string",
      "enum": [
        "security",
        "retainer"
      ],
      "description": "security: held against damage or non-payment. retainer: held against work not yet invoiced"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "Defaults to your business default currency"
    },
    "received_date": {
      "type": "string",
      "description": "YYYY-MM-DD, the day the money arrived. Defaults to today"
    },
    "reference": {
      "type": "string",
      "maxLength": 200,
      "description": "Bank reference, transfer note or cheque number the money arrived with"
    },
    "notes": {
      "type": "string",
      "maxLength": 10000,
      "description": "Free text kept on the record and printed on the statement"
    },
    "client_email": {
      "type": "string",
      "maxLength": 320,
      "description": "Only if the user gave it; otherwise the stored client's email is used"
    },
    "client_address": {
      "type": "string",
      "maxLength": 2000,
      "description": "Postal address for the statement's client block, newlines allowed"
    },
    "client_vat_id": {
      "type": "string",
      "maxLength": 64,
      "description": "Client VAT / tax registration id"
    }
  },
  "required": [
    "client",
    "amount_minor",
    "kind"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List deposits newest first: DEP number, client, kind, date, reference and what was received, applied, refunded and still held, with the same four totalled per currency. Filter by client, status, kind, date.

{
  "type": "object",
  "properties": {
    "client": {
      "type": "string",
      "description": "Only deposits for this client id, exact name, or a name containing this text"
    },
    "status": {
      "type": "string",
      "enum": [
        "held",
        "applied",
        "refunded",
        "all"
      ],
      "description": "Default \"all\". held means some of the money is still held"
    },
    "kind": {
      "type": "string",
      "enum": [
        "security",
        "retainer",
        "all"
      ],
      "description": "Default \"all\""
    },
    "from": {
      "type": "string",
      "description": "YYYY-MM-DD, earliest received date"
    },
    "to": {
      "type": "string",
      "description": "YYYY-MM-DD, latest received date"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Apply part of a held deposit to one invoice: it records that amount as a PAYMENT through the invoice server. amount_minor defaults to the lesser of held and owed. More than either, or a pre-arrival date, is refused.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "Deposit id such as DEP-2026-0001, or an exact client name"
    },
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "The invoice number to apply it to, e.g. INV-2026-0001"
    },
    "amount_minor": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 1000000000000,
      "description": "How much of the deposit to apply, in minor units. Defaults to the smaller of what is held and what the invoice still owes"
    },
    "date": {
      "type": "string",
      "description": "YYYY-MM-DD, the day the deposit was set against the invoice. Defaults to today"
    },
    "note": {
      "type": "string",
      "maxLength": 10000,
      "description": "Free text kept on the application row"
    }
  },
  "required": [
    "id",
    "invoice"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Give part or all of a held deposit back to the client, with the date and how it was sent. Refuses more than is still held. The invoice server is not touched: a refund is not a payment.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "Deposit id such as DEP-2026-0001, or an exact client name"
    },
    "amount_minor": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 1000000000000,
      "description": "How much to give back, in minor units. Defaults to everything still held"
    },
    "date": {
      "type": "string",
      "description": "YYYY-MM-DD, the day the money went back. Defaults to today"
    },
    "method": {
      "type": "string",
      "maxLength": 200,
      "description": "How it was sent, e.g. \"bank transfer to the account it came from\". Printed on the statement"
    },
    "note": {
      "type": "string",
      "maxLength": 10000,
      "description": "Free text kept on the refund row"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Delete a deposit that never moved money, freeing that month's free-tier slot. One with anything applied or refunded is refused, naming it, since a payment or refund would be left with nothing behind it.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "Deposit id such as DEP-2026-0001, or an exact client name"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Answer "how much of theirs am I holding?" for one client or everyone: received, applied to invoices, refunded and still held, one row per currency, never added across them. Reads only; deposit_list shows each deposit.

{
  "type": "object",
  "properties": {
    "client": {
      "type": "string",
      "description": "Client id, exact name or a name containing this text. Leave out for every client"
    },
    "as_of": {
      "type": "string",
      "description": "YYYY-MM-DD, count only deposits received on or before this day"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Turn one client's deposits into a plain-text statement to paste into an email: every movement in date order and the closing balance held. Pass currency when they have more than one. Also a .txt download link valid one hour. Free on every tier.

{
  "type": "object",
  "properties": {
    "client": {
      "type": "string",
      "minLength": 1,
      "description": "Client id, exact name or a name containing this text"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "Only needed when the client has deposits in more than one currency"
    },
    "as_of": {
      "type": "string",
      "description": "YYYY-MM-DD printed as the statement date. Defaults to today"
    },
    "greeting": {
      "type": "string",
      "description": "Opening line, default \"Hello\" plus the client name"
    },
    "sign_off": {
      "type": "string",
      "description": "Closing line, default your business name from the shared profile"
    }
  },
  "required": [
    "client"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Call this tool to render one client's A4 deposit statement and return a download link valid for one hour. Titled DEPOSIT STATEMENT, every movement in date order, closing with what is still held. Pro.

{
  "type": "object",
  "properties": {
    "client": {
      "type": "string",
      "minLength": 1,
      "description": "Client id, exact name or a name containing this text"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "Only needed when the client has deposits in more than one currency"
    },
    "as_of": {
      "type": "string",
      "description": "YYYY-MM-DD printed as the statement date. Defaults to today"
    },
    "out_path": {
      "type": "string",
      "description": "Name for the downloaded file, e.g. acme-deposits. Defaults to the client and currency; the statement comes back as a download link valid for one hour"
    }
  },
  "required": [
    "client"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The deposit book at a date: held per currency, received, applied and refunded, the oldest holdings with days held, and every deposit older than N days with nothing applied. Pro; deposit_balance is free.

{
  "type": "object",
  "properties": {
    "older_than_days": {
      "type": "integer",
      "minimum": 0,
      "maximum": 36500,
      "description": "Flag deposits received this many days ago or more with nothing applied. Default 90"
    },
    "as_of": {
      "type": "string",
      "description": "YYYY-MM-DD to count from. Defaults to today"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "How many oldest held deposits to list. Default 10"
    }
  },
  "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#"
}