catalogue

Add a catalogue line or reprice one: a code, a name, a unit, an optional VAT rate, and price_minor in whole minor units for one currency, tier and valid_from. A repriced line keeps its old rows. Free: 25 SKUs, one tier.

{
  "type": "object",
  "properties": {
    "sku": {
      "type": "string",
      "maxLength": 64,
      "description": "The code, e.g. WEB-AUDIT. Upper case, no spaces. This is what an invoice line is filed under"
    },
    "name": {
      "type": "string",
      "maxLength": 200,
      "description": "What it is on the customer's document, e.g. Website audit"
    },
    "unit": {
      "type": "string",
      "maxLength": 40,
      "description": "What one of it is: each, hour, month, 1000 words. Default each. Required the first time"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "ISO code this price is in. Defaults to the shared business profile's currency"
    },
    "price_minor": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000000,
      "description": "The price of ONE, in whole minor units. 45000 is EUR 450.00. Never a decimal"
    },
    "tier": {
      "type": "string",
      "maxLength": 40,
      "description": "Price tier, e.g. trade or list. Default standard. A second tier is Pro"
    },
    "valid_from": {
      "type": "string",
      "maxLength": 10,
      "description": "The first day this price applies, YYYY-MM-DD. Default today"
    },
    "vat_rate": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000,
      "description": "VAT percent for this product, overriding the shared profile's default on a resolved line"
    },
    "note": {
      "type": "string",
      "maxLength": 2000
    },
    "duplicate_ok": {
      "type": "boolean",
      "description": "Add it even though another code already carries the same product at the same price. Default false"
    }
  },
  "required": [
    "sku",
    "name",
    "price_minor"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Show the price of one SKU as of a date, in one currency and tier: the row picked is the latest valid_from at or before that date, and the answer names the row and any later one already booked. Free.

{
  "type": "object",
  "properties": {
    "sku": {
      "type": "string",
      "maxLength": 200,
      "description": "The SKU code, e.g. WEB-AUDIT, or the product name when only one product carries it"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day the price is wanted for, YYYY-MM-DD. Default today"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "Defaults to the shared business profile's currency"
    },
    "tier": {
      "type": "string",
      "maxLength": 40,
      "description": "Price tier. Default standard"
    }
  },
  "required": [
    "sku"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List catalogue lines with the price in force today, filtered by code prefix, by currency and by tier. A SKU with no price in that currency and tier is listed and said to have none. Free.

{
  "type": "object",
  "properties": {
    "prefix": {
      "type": "string",
      "maxLength": 64,
      "description": "Only codes starting with this, e.g. HOST- for every hosting line"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "The currency the price in force is shown in. Defaults to the profile's"
    },
    "tier": {
      "type": "string",
      "maxLength": 40,
      "description": "Price tier. Default standard"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "Show the price in force on this day instead of today, 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 catalogue line no rate card points at and that never priced a resolved line, freeing a free-tier slot. Otherwise it is refused, naming what depends on it: reprice it to withdraw it instead.

{
  "type": "object",
  "properties": {
    "sku": {
      "type": "string",
      "maxLength": 200,
      "description": "The SKU code, e.g. WEB-AUDIT, or the product name when only one product carries it"
    }
  },
  "required": [
    "sku"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Set the hourly charge-out rate on a labour card: role, currency, hourly_minor in whole MINOR units and the day it starts. The same role, currency and date REPLACES that row rather than adding one. Free.

{
  "type": "object",
  "properties": {
    "role": {
      "type": "string",
      "maxLength": 64,
      "description": "The role charged for, e.g. senior developer. Lower case, this is what an hours line is priced from"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "ISO code this rate is in. Defaults to the shared business profile's currency"
    },
    "hourly_minor": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000000,
      "description": "The hourly rate in whole minor units. 8500 is EUR 85.00 an hour. Never a decimal"
    },
    "valid_from": {
      "type": "string",
      "maxLength": 10,
      "description": "The first day this rate applies, YYYY-MM-DD. Default today"
    },
    "sku": {
      "type": "string",
      "maxLength": 64,
      "description": "A catalogue code this role bills under, so a resolved hours line carries the SKU's name and VAT rate"
    },
    "note": {
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": [
    "role",
    "hourly_minor"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Show the hourly rate for a role as of a date and currency: the row picked is the latest valid_from at or before that date, and the answer names it. With no role given, lists every card. Free.

{
  "type": "object",
  "properties": {
    "role": {
      "type": "string",
      "maxLength": 64,
      "description": "The role, e.g. senior developer. Omit to list every rate card"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day the rate is wanted for, YYYY-MM-DD. Default today"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "Defaults to the shared business profile's currency"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Turn a list of sku or role lines into invoice_create-ready and quote_create-ready items priced from the catalogue as of each line's date. An unknown code is refused by name and never priced. Free.

{
  "type": "object",
  "properties": {
    "lines": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "maxLength": 200,
            "description": "A catalogue code or product name. One of sku or role, never both"
          },
          "role": {
            "type": "string",
            "maxLength": 64,
            "description": "A rate card role. One of sku or role, never both"
          },
          "quantity": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 1000000,
            "description": "How many, for a sku line"
          },
          "hours": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 100000,
            "description": "Hours worked, for a role line"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Za-z]{3}$",
            "description": "Overrides the call's currency for this line. Every line on one payload must agree"
          },
          "date": {
            "type": "string",
            "maxLength": 10,
            "description": "The day this line is priced as of, YYYY-MM-DD. Overrides the call's date"
          },
          "tier": {
            "type": "string",
            "maxLength": 40,
            "description": "Price tier for this line. Overrides the call's tier"
          },
          "description": {
            "type": "string",
            "maxLength": 2000,
            "description": "Override the catalogue name on the customer's document"
          }
        },
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 200,
      "description": "The lines to price, each a sku with a quantity or a role with hours"
    },
    "client": {
      "type": "string",
      "maxLength": 200,
      "description": "Client name or id, copied into both payloads. invoice_create and quote_create both need one"
    },
    "currency": {
      "$ref": "#/properties/lines/items/properties/currency",
      "description": "The currency for every line. Defaults to the shared business profile's"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day the whole list is priced as of, YYYY-MM-DD. Default today"
    },
    "tier": {
      "type": "string",
      "maxLength": 40,
      "description": "Price tier for every line. Default standard"
    },
    "tax_rate": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000,
      "description": "VAT percent for lines whose SKU carries no rate of its own, overriding the shared profile"
    }
  },
  "required": [
    "lines"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Print the price list as plain text: every SKU with its unit, the price in force on a date and any later price booked, then the labour rate cards, under your business name. Also a .txt download link valid one hour. Free; price_list_pdf writes the A4 page.

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day the list is in force, YYYY-MM-DD. Default today"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "Defaults to the shared business profile's currency"
    },
    "tier": {
      "type": "string",
      "maxLength": 40,
      "description": "One tier, or omit for standard. Pass all for every tier, which is Pro"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Call this tool to render the price list for one currency and tier as an A4 HTML document laid out for print-to-PDF (this hosted endpoint has no PDF renderer) and return a download link valid for one hour: every SKU with its unit, its price in force and the day that price started. Pro.

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day the list is in force, YYYY-MM-DD. Default today"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "Defaults to the shared business profile's currency"
    },
    "tier": {
      "type": "string",
      "maxLength": 40,
      "description": "One tier. Default standard"
    },
    "out_path": {
      "type": "string",
      "maxLength": 1000,
      "description": "Name for the downloaded file, e.g. trade-prices-april. Defaults to price-list-<currency>-<tier>-<date>; the list comes back as a download link valid for one hour"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Report the catalogue as at date: how many SKUs there are, how many price rows are in force, which rows a later row already replaces, and which SKUs carry no price in the profile's default currency. Reads only. Pro.

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day the report is in force, YYYY-MM-DD. Default today"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "Maximum rows listed in each section, default and ceiling 500"
    }
  },
  "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#"
}