Skip to content
Website BuddyWebsite BuddyWebsite builder
Sign inGet started
API reference/Client billing

Write a client invoice

Try it

Writes a DRAFT invoice to one of your clients (it takes the account's next number). Nothing reaches the client until send_invoice. due_days is counted again from the day it is sent.

POST/api/v1/invoices

Authentication

An API key as Authorization: Bearer or x-api-key. It needs the invoices:write scope — write, send, mark paid and void client invoices; run monthly invoices; start and stop card autopay.

invoices:writeChanges the draft or a recordIdempotency-Key requiredMCP tool: create_invoice

Parameters

Named placeholders go in the path; the rest in a JSON body.

client_idstringBody · required
The client's id.1 to 100 characters
site_idstringBody · optional
The site it is for, if any.1 to 100 characters
periodstringBody · optional
The month it is for, if any.
linesarray of objectBody · required
due_daysintegerBody · optional
0 to 120Default 14
notestringBody · optional
Printed on the invoice.At most 1000 characters

Response

201 with JSON on success (schema on the right). Errors use the standard envelope; a retry with the same Idempotency-Key gets the first answer back (how retries work).

curl
curl -X POST 'https://websites.workflowcorp.com/api/v1/invoices' \
  -H "Authorization: Bearer $WEBSITEBUDDY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"CLIENT_ID","site_id":"SITE_ID","period":"2026-10","lines":[{"description":"Website — October","unit_cents":7900},{"description":"Two extra pages","quantity":2,"unit_cents":2500}],"due_days":14,"note":"Thank you for your business."}'
Example arguments
{
  "client_id": "CLIENT_ID",
  "site_id": "SITE_ID",
  "period": "2026-10",
  "lines": [
    {
      "description": "Website — October",
      "unit_cents": 7900
    },
    {
      "description": "Two extra pages",
      "quantity": 2,
      "unit_cents": 2500
    }
  ],
  "due_days": 14,
  "note": "Thank you for your business."
}
Response schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "number": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "label": {
      "type": "string",
      "description": "\"INV-1001\"."
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "sent",
        "paid",
        "void"
      ]
    },
    "client_id": {
      "type": "string"
    },
    "client_name": {
      "type": "string"
    },
    "site_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "site_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "period": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "YYYY-MM the invoice is for, if any."
    },
    "lines": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          },
          "quantity": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "unit_cents": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "total_cents": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "description",
          "quantity",
          "unit_cents",
          "total_cents"
        ],
        "additionalProperties": false
      }
    },
    "total_cents": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "currency": {
      "type": "string"
    },
    "issued_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "due_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "paid_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "monthly": {
      "type": "boolean",
      "description": "Made by the monthly run (one per site per month)."
    },
    "on_autopay": {
      "type": "boolean",
      "description": "Charged to the client's card on file — it marks itself paid; mark_invoice_paid is refused."
    },
    "paid_by_card": {
      "type": "boolean"
    },
    "pay_link": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The client's card payment page, while it waits for payment and cards are on."
    },
    "emailed_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "is_sample": {
      "type": "boolean"
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "number",
    "label",
    "status",
    "client_id",
    "client_name",
    "site_id",
    "site_name",
    "period",
    "lines",
    "total_cents",
    "currency",
    "issued_at",
    "due_at",
    "paid_at",
    "note",
    "monthly",
    "on_autopay",
    "paid_by_card",
    "pay_link",
    "emailed_at",
    "is_sample",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}