subscriptions

Define a repeating invoice: a client, the line items, how often to bill, and when it starts and ends. Returns the schedule id, a summary and its next dates. Nothing is invoiced until invoice_generate_due runs.

{
  "type": "object",
  "properties": {
    "client": {
      "type": "string",
      "description": "Client name or id, as in the invoice server. Unknown names are created on the first generated invoice"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          },
          "quantity": {
            "type": "number",
            "minimum": -1000000000000,
            "maximum": 1000000000000,
            "description": "Hours, units or 1 for a flat fee"
          },
          "unit_price": {
            "type": "number",
            "minimum": -1000000000000,
            "maximum": 1000000000000,
            "description": "Price per unit in major units, e.g. 90 for 90 EUR"
          },
          "tax_rate": {
            "type": "number",
            "minimum": -100,
            "maximum": 1000,
            "description": "VAT percent for this line, overrides the business default"
          }
        },
        "required": [
          "description",
          "quantity",
          "unit_price"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 200,
      "description": "The line items billed every period"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "Defaults to your business default currency"
    },
    "every": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "weekly",
            "monthly",
            "quarterly",
            "yearly"
          ]
        },
        {
          "type": "object",
          "properties": {
            "days": {
              "type": "integer",
              "minimum": 1,
              "maximum": 3650
            }
          },
          "required": [
            "days"
          ],
          "additionalProperties": false
        }
      ],
      "description": "How often to bill: \"weekly\", \"monthly\", \"quarterly\", \"yearly\", or {days: 10}. Month steps keep the start date's day of month and clamp it to shorter months, so a schedule starting on the 31st bills on the 28th/29th in February and back on the 31st in March"
    },
    "start_date": {
      "type": "string",
      "description": "YYYY-MM-DD. The first invoice falls on this date, and for weekly/monthly/quarterly/yearly steps its day of month is the billing day for every later period"
    },
    "end_date": {
      "type": "string",
      "description": "YYYY-MM-DD, INCLUSIVE: an occurrence landing exactly on it is still generated"
    },
    "due_days": {
      "type": "integer",
      "description": "Days until each invoice is due, defaults to your payment terms"
    },
    "notes": {
      "type": "string",
      "description": "Free text printed under the totals of every generated invoice"
    },
    "tax_note": {
      "type": "string",
      "description": "Why this schedule bills the tax it bills, e.g. 'Reverse charge: VAT accounted for by the recipient, art. 196 Directive 2006/112/EC'. It is printed under the totals of EVERY invoice this schedule generates, so a 0% retainer carries its reason on the document instead of only in the chat"
    },
    "auto_generate": {
      "type": "boolean",
      "description": "Marks the schedule for the monthly_billing_run prompt. Default false. Nothing runs in the background either way: invoices are created only when invoice_generate_due is called"
    },
    "anchor_day": {
      "type": "integer",
      "minimum": 1,
      "maximum": 31,
      "description": "Pro: bill on this day of month instead of the start date's day. 31 means the last day of every month"
    },
    "end_of_month": {
      "type": "boolean",
      "description": "Pro: always bill on the last day of the month"
    }
  },
  "required": [
    "client",
    "items",
    "every",
    "start_date"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List schedules: id, client, cadence, per-period amount and currency, start and end dates, status, next due date and auto_generate. Filter by status; a paused schedule reports no next due date.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused"
      ]
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return one schedule in full by id or client: items, cadence, dates, due days, anchor rules, notes, per-period amount, next due date and how many invoices it generated. schedule_history is the log.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Schedule id, or a client name"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Change one schedule by id: client, items, currency, cadence, dates, due_days, notes or auto_generate. Only the fields you pass change. Periods already invoiced are never re-issued, so a new amount applies to future ones.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "client": {
      "type": "string"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          },
          "quantity": {
            "type": "number",
            "minimum": -1000000000000,
            "maximum": 1000000000000,
            "description": "Hours, units or 1 for a flat fee"
          },
          "unit_price": {
            "type": "number",
            "minimum": -1000000000000,
            "maximum": 1000000000000,
            "description": "Price per unit in major units, e.g. 90 for 90 EUR"
          },
          "tax_rate": {
            "type": "number",
            "minimum": -100,
            "maximum": 1000,
            "description": "VAT percent for this line, overrides the business default"
          }
        },
        "required": [
          "description",
          "quantity",
          "unit_price"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 200
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "every": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "weekly",
            "monthly",
            "quarterly",
            "yearly"
          ]
        },
        {
          "type": "object",
          "properties": {
            "days": {
              "type": "integer",
              "minimum": 1,
              "maximum": 3650
            }
          },
          "required": [
            "days"
          ],
          "additionalProperties": false
        }
      ],
      "description": "How often to bill: \"weekly\", \"monthly\", \"quarterly\", \"yearly\", or {days: 10}. Month steps keep the start date's day of month and clamp it to shorter months, so a schedule starting on the 31st bills on the 28th/29th in February and back on the 31st in March"
    },
    "start_date": {
      "type": "string"
    },
    "end_date": {
      "type": [
        "string",
        "null"
      ],
      "description": "null clears the end date"
    },
    "due_days": {
      "type": "integer"
    },
    "notes": {
      "type": "string"
    },
    "tax_note": {
      "type": "string",
      "description": "Replace the tax reason carried onto every future generated invoice. Pass an empty string to clear it"
    },
    "auto_generate": {
      "type": "boolean"
    },
    "anchor_day": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 31
        },
        {
          "type": "null"
        }
      ],
      "description": "Pro"
    },
    "end_of_month": {
      "type": "boolean",
      "description": "Pro"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Stop one schedule generating invoices without deleting it; invoice_generate_due and forecast skip it. Its periods keep falling due and resuming back-bills them, so use schedule_skip to drop just one.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Make a paused schedule active again. Every period missed while it was paused is still due and the next invoice_generate_due creates them all. Refused when it would pass the free tier's 3 active.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Delete one schedule permanently. Invoices already generated stay in the invoice server and the history is kept. Re-creating it gives a NEW id, so its old periods count as unbilled. schedule_pause is reversible.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Schedule id, or a client name. Deletion is permanent; re-creating the same schedule afterwards gives it a NEW id, so its old periods count as unbilled again"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Close ONE occurrence for good without pausing the schedule, reporting what will not be billed. period must be a real occurrence of it. An invoiced period is refused; undo reopens a skip.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Schedule id, or a client name"
    },
    "period": {
      "type": "string",
      "description": "The occurrence date to skip, YYYY-MM-DD, exactly as it appears in schedule_upcoming or forecast. This is the answer to \"pause this client for October\": schedule_pause stops the whole schedule and a resumed schedule still back-bills the periods it missed, whereas a skipped period is closed for good"
    },
    "undo": {
      "type": "boolean",
      "description": "Remove a previous skip so the period becomes due again. Works only on a period that has not been invoiced. Default false"
    }
  },
  "required": [
    "id",
    "period"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Table every occurrence of every ACTIVE schedule due in the next N days (30 default), with its amount and the invoice due date, plus a total per currency. Free lists the first 3 in your horizon.

{
  "type": "object",
  "properties": {
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3650,
      "description": "Days ahead, default 30. The free tier honours the horizon you ask for and lists the first 3 occurrences in it; Pro lists them all"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Create a real invoice in the invoice server for every schedule occurrence on or before as_of that has not been invoiced yet, and render each PDF. Returns what was created, what was skipped and what is still due.

{
  "type": "object",
  "properties": {
    "as_of": {
      "type": "string",
      "description": "YYYY-MM-DD, defaults to today. Every occurrence on or before this date that has not been invoiced is billed. Idempotent: one invoice per schedule per period, keyed by the occurrence date, so running it twice creates nothing the second time"
    },
    "schedule_id": {
      "type": "string",
      "description": "Only this schedule. Free and unlimited on every tier"
    },
    "dry_run": {
      "type": "boolean",
      "description": "List what would be created without creating anything. Default false. One run creates at most 60 invoices, oldest period first"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The audit log for one schedule id, oldest first: period, invoice number, issue and due dates, amount, PDF path, and whether that invoice is unpaid, paid, skipped or since deleted. schedule_list finds the id. Pro.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Expected invoiced revenue per calendar month per currency from active schedules. Invoiced and skipped periods are excluded and paused schedules listed apart. Free: 3 months; Pro: up to 120.

{
  "type": "object",
  "properties": {
    "months": {
      "type": "integer",
      "minimum": 1,
      "maximum": 120,
      "description": "Months ahead including this one, default 12"
    }
  },
  "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#"
}