Creates a draft invoice, bill, expense, cash sale, credit note or supplier credit. A draft is not in the books and has no number; approve it to record it. Invoices and bills are settled later by payments; expenses and cash sales were paid on the spot and name the money account used; credit notes and supplier credits reverse sales or purchases and are applied to invoices or bills, or refunded.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
Body
kindstring, required | invoice (a sale the customer pays later), bill (a purchase you pay later), expense (a purchase already paid), cash_sale (a sale paid on the spot), credit_note (takes a sale back and lowers what a customer owes), or supplier_credit (takes a purchase back and lowers what you owe a supplier). The kind cannot be changed later. |
contact_idstring | Id of a contact. Required for invoice, bill, credit_note and supplier_credit; optional for expense and cash_sale. Sales kinds (invoice, cash_sale, credit_note) need a customer or both; purchase kinds (bill, expense, supplier_credit) need a supplier or both. |
issue_datedate, required | The document's date, YYYY-MM-DD. The entry is recorded on this date when approved, so its month must be open by then. |
due_datedate | When an invoice or bill must be paid, YYYY-MM-DD. Defaults to issue_date (due on receipt). Ignored for other kinds, whose due date is always the issue date. |
referencestring | Your own reference, such as the supplier's invoice number or a purchase order number. |
memostring | A note on the document. |
created_bystring, required | Who prepared the draft, such as a user's email or name. Kept on the document and its entry. |
money_accountstring | Expense and cash_sale only: code of the account the money was paid from or into, such as 1000 (Cash) or 1010 (Bank account). Must be an asset account; for an expense it can also be an equity account such as 3000 when the owner paid personally. Can be left out on the draft but is needed before approval. Must be left out for invoice, bill, credit_note and supplier_credit. |
party_namestring | The other party's name when there is no contact, such as the shop on a receipt. Used in the entry's description and in duplicate checks. |
attachment_refstring | A reference to a stored file for this document. Set by the receipts endpoint; usually left out. |
confidencenumber | From 0 to 1: how sure whoever prepared the draft (for example an AI reader) was that it is right. Informational only. |
currencystring | Three-letter currency code of the document, such as USD or AED. Defaults to the business's currency. Line amounts are in this currency's smallest unit. |
ratenumber | For a document in another currency: how many units of the business's currency one unit of this currency is worth on the issue date (for example 3.64 for USD to QAR). If left out it is looked up from your exchange rates and BasePipe's fixed pegs; a document with no rate can be saved but not approved. |
branchstring | Name or id of a branch tag for the whole document. Lines without their own branch use it. |
projectstring | Name or id of a project tag for the whole document. Lines without their own project use it. |
linesarray, required | At least one line. The document total is the sum of each line's amount plus its tax (withholding tax is subtracted instead). |
lines[].descriptionstring | What the line is for. Required unless the line names an item, in which case it defaults to the item's name. |
lines[].accountstring | Code of the account the line goes to, such as 4000 (Sales) or 6000 (Rent). Each line needs account or item. With an item on a sales document it defaults to the item's sales account and must be an income account; on a purchase document the line always goes to the item's stock account, and any account given must be that one. |
lines[].itemstring | Code of a stock item. Approving the document moves stock: bills and expenses bring it in at the line amount, invoices and cash sales take it out at average cost, credit notes bring returns back in, supplier credits send it back out. |
lines[].quantitynumber | How many, above zero. Defaults to 1. Can have decimals, such as 2.5 kg. |
lines[].unit_priceinteger, required | Price of one unit before discount and tax, in the smallest unit of the document's currency (12.50 QAR is 1250). Must be above zero. |
lines[].discountinteger | An amount taken off the line, in the smallest currency unit. 0 means no discount. Must be less than quantity x unit_price. Give discount or discount_percent, not both. |
lines[].discount_percentnumber | A percentage taken off quantity x unit_price, from 0 up to but not including 100; the result is rounded to the nearest unit. Give discount or discount_percent, not both. |
lines[].taxstring | Code of a tax code set up for the business. Leave the field out to use the contact's default tax code; send null for no tax. Output (sales) codes only go on invoices, cash sales and credit notes; input and withholding codes only on bills, expenses and supplier credits. Tax is the line amount (after discount) x the code's rate, rounded. |
lines[].branchstring | Name or id of a branch tag for this line only. |
lines[].projectstring | Name or id of a project tag for this line only. |
Example
{
"kind": "invoice",
"contact_id": "01936f4e-8a2b-7c3d-9e4f-5a6b7c8d9e0f",
"issue_date": "2026-11-16",
"due_date": "2026-12-16",
"reference": "PO-4471",
"memo": "Catering for the National Day staff lunch",
"created_by": "[email protected]",
"lines": [
{
"description": "Lunch buffet, per person",
"account": "4000",
"quantity": 40,
"unit_price": 6500,
"discount_percent": 10
},
{
"description": "Delivery and setup",
"account": "4100",
"quantity": 1,
"unit_price": 25000,
"tax": null
}
]
}
Returns
201 with the draft document: id, kind, status (draft), number (null until approved), contact {id, name}, party_name, money_account, attachment_ref, confidence, currency, rate, base_total (null until approved), issue_date, due_date, reference, memo, total, paid, outstanding, created_by, created_at, approved_by, recorded_at, entry_id, voided_by, voided_at, void_reason, branch, project, order_id, recurring_id, lines [{line_no, description, account, item, quantity, unit_price, discount, amount (quantity x unit_price less discount), tax, tax_amount}], credits.
Errors
- 400 invalid_request: the body is not a JSON object; kind is not one of the six kinds; issue_date or due_date is not YYYY-MM-DD; created_by is missing; contact_id is not an id; currency is not three letters; rate is not above zero; confidence is not from 0 to 1.
- 400 invalid_request: lines is empty; a line has neither account nor item; a line has no description and no item; quantity is not above zero; unit_price or discount is not a whole number above zero; both discount and discount_percent are given; discount_percent is not from 0 up to 100.
- 404 not_found: the business does not exist or is not visible to this key.
- 422 rejected: an invoice, bill or credit has no contact; the contact is not in this business, or is a supplier on a sale or a customer on a purchase.
- 422 rejected: a money_account is given on an invoice, bill or credit; the money account is not in the books or is not a bank, cash (or, for an expense, owner's) account.
- 422 rejected: a line's account, item, tax code, branch or project is not in the business or is switched off; an item sold goes to a non-income account; a purchase line with an item names an account other than the item's stock account; a tax code is on the wrong side (sales vs purchases); a discount takes the whole line.
- 422 rejected: the currency is not one BasePipe knows; the business is read-only because its plan is unpaid.