Invoices: create invoice draft
invoices_create_draftCreate an invoice draft for a customer. Provide company information, line items with pricing and VAT, and optional settings like discounts or recurring intervals.
Instructions
🟡 WRITE · creates data — Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent — calling twice may create duplicates. create invoice draft Add an invoice draft for the specified customer.
Endpoint: POST /invoices/create/draft
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | The zip of the recipient company. If specified, the field will be validated. | |
| city | No | The city of the recipient company. If specified, the field will be validated. | |
| date | Yes | The date of the invoice. | |
| type | Yes | Can be either 'invoice' ("Rechnung"), 'credit' ("Gutschrift") or 'offer' ("Angebot"). | |
| No | The email for sending the invoice. If specified, the field will be validated. | ||
| street | No | The street of the recipient company. If specified, the field will be validated. | |
| api_key | No | Optional. The BB customer api_key to act on. Defaults to the BB_API_KEY configured on the server — only set this to target a different customer. | |
| country | No | The country of the recipient company. If specified, the field will be validated. Valid cases are only the German version of the country name [Dänemark] OR the two digit ISO code of the country [DK]. | |
| item_vat | Yes | An array of invoice item vats. Usage: "item_vat" : ['7', '19'] Valid vat rates are floating point numbers between 0 and 100. | |
| item_name | Yes | An array of invoice items. Usage: "item_name" : ['Item 1', 'Item 2'] | |
| item_unit | Yes | An array of invoice items units. Usage: "item_unit" : ['Std.', 'Stk.'] | |
| item_amount | Yes | An array of invoice item amounts. Usage: "item_amount" : ['10', '20'] | |
| company_name | Yes | The company name of the recipient. | |
| discount_type | No | The type of the discount. Can be either 'percent' or 'EUR'. If specified, the field will be validated. | |
| show_bankdata | No | Show the the bank data on the invoice. If specified, the field will be validated. | |
| correspondence | No | The optional correspondence to the invoice recipient. If specified, the field will be validated. | |
| date_of_supply | No | Date or period of service/delivery. NOTE: The date_of_supply will be displayed on the PDF, but when the date AND the date_of_supply is specified in the format "YYYY-MM-DD", the date_of_supply will also be taken over as date_delivery of the receipt in the 'Belege' or 'Belege/Buchen' view. IMPORTANT: Due to the DATEV compatibility, we cannot accept a date_of_supply that is after the invoice date. In that case it will be ignored! | |
| discount_value | No | The value of granted discount. If specified, the field will be validated. | |
| customer_number | No | The customer number of the recipient. If specified, the field will be validated. | |
| final_provisions | No | The final comment of the invoice. If specified, the field will be validated. | |
| item_description | No | An array of invoice item description. Usage: "item_description" : ['Description Item 1', 'Description Item 2']. If specified, the field will be validated. | |
| show_contactdata | No | Show the contact data on the invoice. If specified, the field will be validated. | |
| show_prices_type | Yes | Can be either 'net' ("Netto") or 'gross' ("Brutto"). | |
| item_single_price | Yes | An array of invoice item single_prices. Usage: "item_single_price" : ['20', '19.99'] | |
| payment_conditions | No | The payment conditions of the invoice. If specified, the field will be validated. | |
| recurring_interval | No | An interval for recurring invoices. Can be either 'weekly', 'monthly', 'quarterly' or 'yearly'. If specified, the field will be validated. | |
| contact_person_name | No | The name of the contact person of the recipient company. If specified, the field will be validated. | |
| recurring_date_next | No | The next date of a recurring invoice. IMPORTANT: The field is required, if "recurring_interval" is specified. If specified, the field will be validated. | |
| additional_addressline | No | The additional address information of the recipient company. If specified, the field will be validated. |