invoice_create
ONE call creates the whole document: claims the next invoice number, then writes the header plus every line in items ([{description, quantity, unit_price_cents}], integer CENTS). client_name finds a client by name or creates one. Birth status 'paid' needs items in the same call. tax_scheme sg_gst or my_sst taxes each line by its tax_code (refusals: see tax_scheme). When present, the second content block is the invoice as copy-ready text, shown with a Copy button where the host draws MCP Apps; if the user says they cannot see the invoice, give them that block word for word; share:true adds a client link, only when the user asks for one. NEXT: invoice_payment_record to record money-in.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Confirms a create whose notes or single line item read like a payment RECEIVED or a write-off rather than a new bill — resend the SAME call with force:true to create it anyway. No effect on quote_create (the intent trap is invoice-only). | |
| items | No | ONE call creates the whole document — line items in integer CENTS ($15.00 → 1500), or unit_price as a decimal string. quantity takes up to 3 decimals (1.5 hours → 1.5); unit is an optional label (hr, kg); discount_bps is an optional line discount (10% → 1000). tax_code is the line's tax under the document's tax_scheme (sg_gst: standard, zero_rated, exempt, out_of_scope, default standard; my_sst: sales_10, sales_5, service_8, service_6, exempt, required); refused without a tax_scheme. | |
| notes | No | ||
| share | No | Only when the user asks for a link: true also returns share_url (the client's link to view the invoice) and the full document in this same call. Where this environment has no public address, share_path and share_url_unavailable come back instead of share_url. Nothing is sent. | |
| status | No | ||
| paid_at | No | ||
| sent_at | No | ||
| currency | No | ||
| due_date | No | ||
| cash_sale | No | ||
| client_id | No | ||
| source_id | No | ||
| issue_date | No | ||
| line_items | No | Alias of items. | |
| tax_scheme | No | sg_gst (Singapore GST) or my_sst (Malaysia SST): each line is taxed by its tax_code at the rate in force on the issue date. Under a scheme, a tax_rate_bps other than that rate, an unknown tax_code and a my_sst line without one are refused, naming the valid codes and the rate's source. "none" = no scheme, priced by tax_rate_bps. Left out = your sales settings' tax_scheme. | |
| client_name | No | Client by NAME — resolves to an existing client or creates one (no client_id lookup needed). | |
| source_type | No | ||
| fx_rate_date | No | The date the fx rate is for, YYYY-MM-DD. Send with fx_rate_to_sgd. | |
| tax_rate_bps | No | ||
| payment_terms | No | ||
| fx_rate_to_sgd | No | sg_gst invoices in a currency other than SGD: Singapore dollars per 1 unit of the invoice currency as a decimal string, up to 6 decimals ("1.3502"), from a source IRAS accepts (MAS, a local bank, Bloomberg, Reuters, Oanda) for the date of supply. Send with fx_rate_date. Or send fx_rate_to_sgd_ppm (1.3502 → 1350200). | |
| invoice_number | No | ||
| payment_method | No | ||
| fx_rate_to_sgd_ppm | No | ||
| prices_include_tax | No | true = unit prices already include the tax (the tax is worked back out of each line). Default false. Needs a tax_scheme, except on a cash sale (cash_sale 1): its total is then the amount taken, with tax_rate_bps (or your default rate) worked out inside it, as the Quick Sale keypad records it. |