generateInvoice
generateInvoiceGenerates an invoice for a contract and customer over a billing window. Requires exact bill_for_date from getContractBillingCycles to match a billing cycle.
Instructions
Generate an invoice for a single contract+customer over a billing window.
Granularity is PER PHASE, NOT per product. ONE call generates ONE invoice covering ALL products active in the (contract, customer, from_date, to_date) window — every product becomes a line item on the same invoice. NEVER iterate over products.
MANDATORY PRE-STEP: call getContractBillingCycles first to fetch the list of valid {start_date, end_date, bill_for_date, billing_cycle_start_day} entries for this contract. Pick ONE entry. Copy its start_date → from_date, end_date → to_date, bill_for_date, billing_cycle_start_day verbatim. DO NOT compute these from contract.start_date, pricing.billing_period, or human intuition — the backend matches bill_for_date exactly against the pre-computed list.
Date fields accept ISO-8601 strings (e.g. "2026-04-28T00:00:00Z") or integer UNIX seconds. Prefer pasting ISO strings verbatim from getContractBillingCycles output — the server converts to unix internally before sending to the API.
Known failure modes:
• {invoice_ids: []} → bill_for_date did not match any cycle. Re-fetch billingCycles and copy the exact value.
• $0 invoice → bill_for_date/billing_cycle_start_day omitted entirely.
• InvoiceAlreadyGeneratedForThisBillingPeriod → an approved invoice already exists for this cycle.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| contract_id | Yes | UUID of the contract to generate the invoice for. | |
| customer_id | Yes | UUID of the customer. | |
| from_date | Yes | Start of billing period. Accepts ISO-8601 string (e.g. `2026-04-28T00:00:00Z`) or UNIX seconds integer. PREFER ISO string copied verbatim from getContractBillingCycles.start_date — avoids timezone bugs. | |
| to_date | Yes | End of billing period. Accepts ISO-8601 string or UNIX seconds integer. PREFER ISO string copied verbatim from getContractBillingCycles.end_date. | |
| bill_for_date | Yes | REQUIRED. Anchors which billing cycle this invoice belongs to. Accepts ISO-8601 string or UNIX seconds. MUST match exactly one of the `bill_for_date` values returned by getContractBillingCycles — pasting the ISO string verbatim is the safest path. Arbitrary dates produce `invoice_ids: []`. | |
| billing_cycle_start_day | Yes | REQUIRED. Day of month (1-31) anchoring the recurring billing cycle. Fetch from the contract or plan's billing_period; if unsure, use the day-of-month of contract.start_date. Omitting this causes the API to return a $0 invoice because no billing cycle matches. | |
| __userContext | No | Internal user context for multi-tenant authentication and approval workflow |