purchase-order

Credit one invoice: the whole invoice, a GROSS amount_minor split over its VAT rates, or named lines. Amounts store negative, reusing the invoice's own rates. Free: 5 a month. Send it with credit_note_text.

{
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "The invoice number to credit, e.g. INV-2026-0001"
    },
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Why the money is being given back, e.g. \"returned goods\" or \"billed twice\". Printed on the document"
    },
    "amount_minor": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 1000000000000,
      "description": "Credit this GROSS amount, VAT included, in minor units. Split across the invoice's VAT rates in proportion to each rate's share of the total"
    },
    "lines": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "line": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "description": "1-based position of the line on the invoice, as shown by invoice_get"
          },
          "quantity": {
            "type": "number",
            "minimum": -1000000000000,
            "maximum": 1000000000000,
            "exclusiveMinimum": 0,
            "description": "Credit only this many units. Defaults to the whole line"
          }
        },
        "required": [
          "line"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 200,
      "description": "Credit only these invoice lines. Leave out with amount_minor for a full credit note"
    },
    "issue_date": {
      "type": "string",
      "description": "YYYY-MM-DD, defaults to today in your business profile's timezone"
    },
    "notes": {
      "type": "string",
      "maxLength": 10000,
      "description": "Free text printed under the totals"
    }
  },
  "required": [
    "invoice",
    "reason"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List credit notes newest first: id, invoice, client, basis, reason, currency and the NEGATIVE total, with the amount credited per currency. Filter by invoice, client or issue date range.

{
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "description": "Only credit notes issued against this invoice number"
    },
    "client": {
      "type": "string",
      "description": "Only credit notes for clients whose name contains this text"
    },
    "from": {
      "type": "string",
      "description": "YYYY-MM-DD, earliest issue date"
    },
    "to": {
      "type": "string",
      "description": "YYYY-MM-DD, latest issue date"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return one credit note in full by id or exact client name: every negated line, VAT lines, totals, the reason, and the invoice number and date it reverses. Reads only. Use credit_note_list for the ids.

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

Call this tool to render one credit note as an A4 print-ready document and return a download link valid for one hour: the invoice layout titled CREDIT NOTE, with the invoice it reverses. Pro.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Credit note id such as CN-2026-0001"
    },
    "out_path": {
      "type": "string",
      "description": "Name for the downloaded file, e.g. acme-credit. Defaults to the document id; the document comes back as a download link valid for one hour"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Turn a credit note into a plain-text summary to paste into an email: the negated line table, VAT lines, total, reason, and what now comes off the invoice. Also a .txt download link valid one hour. Free; credit_note_pdf writes the A4 document.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Credit note id such as CN-2026-0001"
    },
    "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": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Remove one credit note never posted to its invoice and never rendered, freeing that month's slot; the invoice becomes creditable again. One with a dependent is refused: issue a fresh note to reverse a sent one.

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

Raise a purchase order to a supplier from items and return its PO number and totals. unit_price is in MAJOR units; currency, VAT and the buyer block come from the shared profile. Free: 5 documents a calendar month.

{
  "type": "object",
  "properties": {
    "supplier": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Supplier name or client id. A name the invoice server already knows brings its address, email and VAT id onto the order"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "every line needs a description, 500 characters or fewer"
          },
          "quantity": {
            "type": "number",
            "minimum": -1000000000000,
            "maximum": 1000000000000,
            "exclusiveMinimum": 0,
            "description": "Units ordered, must be greater than zero"
          },
          "unit_price_minor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000000000,
            "description": "Price per unit in MINOR units: 9000 = 90.00 EUR, 90 = JPY 90. Never a decimal"
          },
          "tax_rate": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000,
            "description": "VAT percent for this line, overrides the business default"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Za-z]{3}$",
            "description": "Only to state the line's currency; every line on one document must agree"
          }
        },
        "required": [
          "description",
          "quantity",
          "unit_price_minor"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 200,
      "description": "What is being ordered"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "Defaults to your business default currency"
    },
    "expected_delivery_date": {
      "type": "string",
      "description": "YYYY-MM-DD, when the goods or work are due"
    },
    "issue_date": {
      "type": "string",
      "description": "YYYY-MM-DD, defaults to today in your business profile's timezone"
    },
    "discount_percent": {
      "type": "number",
      "minimum": 0,
      "maximum": 100,
      "description": "Discount applied to every line, in percent"
    },
    "tax_rate": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000,
      "description": "VAT percent for lines with no rate of their own. Defaults to the business default"
    },
    "notes": {
      "type": "string",
      "maxLength": 10000,
      "description": "Free text printed under the totals, e.g. delivery address or terms"
    },
    "supplier_email": {
      "type": "string",
      "maxLength": 320,
      "description": "Only if the user gave it; otherwise the stored client's email is used"
    },
    "supplier_address": {
      "type": "string",
      "maxLength": 2000,
      "description": "Postal address for the SUPPLIER block, newlines allowed"
    },
    "supplier_vat_id": {
      "type": "string",
      "maxLength": 64,
      "description": "Supplier VAT / tax registration id"
    }
  },
  "required": [
    "supplier",
    "items"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List purchase orders newest first: id, supplier, order and expected delivery dates, status open, partially_received or received, currency, total and received date. Filter by status, supplier or date range.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "open",
        "partially_received",
        "received",
        "all"
      ],
      "description": "Default \"all\""
    },
    "supplier": {
      "type": "string",
      "description": "Only orders to suppliers whose name contains this text"
    },
    "from": {
      "type": "string",
      "description": "YYYY-MM-DD, earliest order date"
    },
    "to": {
      "type": "string",
      "description": "YYYY-MM-DD, latest order date"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return one purchase order in full by id or exact supplier name: buyer and supplier blocks, every line with unit price and VAT, totals, the delivery date, status and every receipt with its date and note.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Purchase order id such as PO-2026-0001, or an exact supplier name"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Call this tool to render one purchase order as an A4 print-ready document and return a download link valid for one hour: the invoice layout titled PURCHASE ORDER, with the buyer and supplier. Pro.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Purchase order id such as PO-2026-0001"
    },
    "out_path": {
      "type": "string",
      "description": "Name for the downloaded file, e.g. acme-credit. Defaults to the document id; the document comes back as a download link valid for one hour"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Turn a purchase order into a plain-text order to paste into an email: the line table, VAT lines, total, and a line asking the supplier to deliver by the date and quote the PO number. Also a .txt download link valid one hour. Free on every tier.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Purchase order id such as PO-2026-0001"
    },
    "greeting": {
      "type": "string",
      "description": "Opening line, default \"Hello\" plus the supplier name"
    },
    "sign_off": {
      "type": "string",
      "description": "Closing line, default your business name from the shared profile"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Record that an order arrived. partial keeps it open and can be repeated, each receipt kept with its date and note; a full receipt closes it. An order already received, or a date before the order date, is refused.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Purchase order id such as PO-2026-0001"
    },
    "partial": {
      "type": "boolean",
      "description": "True when only some of the order arrived. The order stays open and can be received again. Default false"
    },
    "date": {
      "type": "string",
      "description": "YYYY-MM-DD, defaults to today"
    },
    "note": {
      "type": "string",
      "maxLength": 10000,
      "description": "What arrived, e.g. \"8 of 10 units, 2 back-ordered\""
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Remove one purchase order with nothing received and never rendered, freeing that month's slot. One with a receipt is refused, naming it. The PO number is never reissued. purchase_order_receive logs arrivals.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Purchase order id such as PO-2026-0001, or an exact supplier name"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Over a date range: what was credited back per currency and against how many invoices, what is still on order per currency, and every open order past its delivery date with days late. Pro; the list tools are free.

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "description": "YYYY-MM-DD, earliest document date to count"
    },
    "to": {
      "type": "string",
      "description": "YYYY-MM-DD, latest document date to count"
    }
  },
  "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#"
}