Invoice payload reference

Both PDF tools accept the same invoice object. invoicepig_generate_pdf receives it directly; invoicepig_generate_pdf_batch receives it in its invoices array.

The object is a strict patch over InvoicePig defaults, so fields are optional at the protocol level but unknown field names are rejected. Provide the information required for a correct business document rather than relying on blank defaults.

Parties, identifiers, and dates

Field	Type	Guidance
`companyName`	string	Invoice issuer. Confirm this role; a receipt merchant is not automatically the issuer.
`billToText` / `shipToText`	string	Customer or delivery name and address; line breaks are allowed.
`invoiceNumberValue` / `poNumberValue`	string	Use a user-supplied identifier; do not invent one.
`invoiceDate` / `dueDate`	ISO date string or `null`	Prefer `YYYY-MM-DD`; use `null` to clear an optional date.
`paymentTermsValue`	string	For example, `Net 14`.
`notesText`	string	Additional non-sensitive invoice notes.

Line items and amounts

Field	Type	Guidance
`items`	array	Each item requires `id`, `description`, `details`, `quantity`, and `rate`. `id` is a non-empty stable string.
`taxRate`	number	Tax percentage or rate used by InvoicePig. Set `showTax` to show it.
`discount`	number	Amount or percent according to `discountType`.
`discountType`	`fixed` or `percent`	Applies to `discount`.
`shipping`	number	Shipping amount; set `showShipping` to show it.
`amountPaid`	number	Paid amount or percent according to `amountPaidType`.
`amountPaidType`	`fixed` or `percent`	Applies to `amountPaid`.
`showTax`, `showDiscount`, `showShipping`, `showAmountPaid`	boolean	Controls whether the matching amount is shown.
`currencyCode`	string	Use an ISO 4217 code such as `USD`, `EUR`, or `THB`.

{
  "items": [
    {
      "id": "consulting-01",
      "description": "Consulting",
      "details": "Discovery workshop",
      "quantity": 2,
      "rate": 150
    }
  ],
  "taxRate": 7,
  "showTax": true,
  "currencyCode": "THB"
}

Payment instructions

Set paymentMethod to one of bank_transfer, local_transfer, crypto, or other, then provide only the matching non-sensitive instructions.

Method	Supported fields
`bank_transfer`	`bankAccountName`, `bankAccountNumber`, `bankName`, `bankSwiftCode`, `bankAddress`
`local_transfer`	`localAccountName`, `localAccountNumber`, `localBankName`
`crypto`	`cryptoWalletAddress`, `cryptoNetwork`, `cryptoCurrency`
`other`	`otherPaymentInstructions`

Never include card numbers, security codes, API keys, passwords, or other secrets.

Presentation

Field	Type	Guidance
`selectedLayout`	enum	One of the supported layout IDs below. Unknown IDs are rejected.
`primaryColor` / `accentColor`	string	Brand colors for the selected layout.
`dateFormat`	string	Display date format.
`logoId`	UUID or `null`	Use an ID returned by `invoicepig_manage_logo` to select a saved private logo. Omit for the signed-in user’s selected default, or use `null` for no logo.
`logoSize`	number	Logo scale percentage from 20–200; use `100` for normal size and `90` for 90%.
`labels`	object	Override invoice labels such as `invoice`, `billTo`, `item`, `quantity`, `rate`, `tax`, `total`, and `notes`.

Supported layout IDs: classic, corporate, formal, minimal, creative, futuristic, luxury, traditional, swiss, and executive.

Validation rules

Each line-item number must be finite; do not send NaN or infinity.
A batch contains 1–10 invoices.
Use invoicepig_manage_logo to add or list private reusable logos, then pass a returned ID as logoId. Do not send image bytes, base64, preview URLs, or arbitrary URLs in an invoice payload.
logoSize must be a percentage from 20–200; use 100 for normal size, never 0.9 for 90%.
Unknown invoice or line-item fields are rejected, allowing an agent to correct misspelled keys.
The server can accept partial data, but incomplete data can yield an incomplete PDF. Ask for missing issuer, customer, currency, line item, and unclear tax treatment before rendering.