--- title: "Create a client invoice" method: POST path: "/v2/client_invoices" tags: ["Client Invoices"] --- # Create a client invoice `POST /v2/client_invoices` OAuth scope: `client_invoice.write` --- Creates a single client invoice for the authenticated organization. See further details below. --- **Price plans**: this endpoint is available for all Qonto price plans. --- The required request attributes are outlined inside Schemas / ClientInvoiceCreatePayload. The response contains the attributes of the client invoice entered in the request, along with additional fields that are computed by Qonto, including the associated invoice id. --- When creating an invoice, note that the invoice "inherits" the currency of the provided client. If the `currency` is not set for that client, you will receive a validation error on the `/data/attributes/currency` field. --- Italian organizations must have e-invoicing activated on the Qonto app in order to use this endpoint. --- ## Headers - `X-Qonto-Staging-Token` string ## Request body - ClientInvoiceCreatePayload - `client_id` string, uuid, required - `issue_date` string, date, required - `performance_date` string, date — represents the date the initiator has issued or shared the invoice as legally viable. The format should be `YYYY-MM-DD` - `due_date` string, date, required — represents the invoice’s payment deadline that is added by the initiator. The format should be `YYYY-MM-DD` - `status` 'draft' | 'unpaid' — represents the status of the invoice. If not filled, `unpaid` will be automatically attributed to the invoice. - `number` string, required — represents the invoice’s number. - `purchase_order` string — represents the purchase order data added by the invoice’s initiator. - `terms_and_conditions` string — represents additional notes added by the invoice’s initiator. - `header` string - `footer` string - `currency` string, required — represents the invoice’s currency for the total amount of the invoice. Currently, only value allowed is EUR. Trigram following ISO 4217 - `payment_methods` object, required — contains payment method details for the invoice. - `iban` string, required — represents the beneficiary’s International Bank Account Number (IBAN). The format must follow ISO 13616, and should be a valid IBAN (must start with two letters, followed by 25 digits). The IBAN must be associated to a Qonto account. - `settings` InvoiceSettingsOverride — This collection of attributes can be optionally used to temporarily override some of the organization's properties for this one invoice. - `vat_number` string - `company_leadership` string - `district_court` string - `commercial_register_number` string - `tax_number` string - `legal_capital_share` object - `value` string - `currency` 'AED' | 'AUD' | 'BGN' | 'CAD' | 'CHF' | 'CNY' | 'CZK' | 'DKK' | 'EUR' | 'GBP' | 'GHS' | 'HKD' | 'HUF' | 'ILS' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RON' | 'RSD' | 'SAR' | 'SEK' | 'SGD' | 'TRY' | 'USD' | 'ZAR' | 'ZMW' - `transaction_type` 'goods' | 'services' | 'goods_and_services' - `vat_payment_condition` 'on_receipts' | 'compensated_for_sales' - `discount_conditions` string, nullable - `late_payment_penalties` string, nullable - `legal_fixed_compensation` string, nullable - `items` DocumentItemPayload[], required - `title` string, required — represents the item’s title. It is displayed as the first line of the item in bold in the invoice table. It indicates in a short sentence the product or service being sold. - `description` string — represents the item’s description of the product or service being sold. It is added below the title of each item in the invoice table. Free format, with a maximum of 300 characters. Use `\n` to indicate line breaks. - `quantity` string, required — represents the item’s quantity of the specific product or services being sold. For example, it can be in hours or in number of products. Decimals should be separated by a period “.” - `unit` string — represents the item’s unit. It is an optional field and allows maximum 20 characters for non Italian organizations. - For Italian organizations, documents are generated in PDF format and in XML format (automatically sent to the Italian tax authorites). In the PDF, unit will appear with a maximum of 20 characters. In the XML file, it is truncated down to the first 10 characters. - For French organizations, documents are generated under the Factur-X format (a structured PDF file with an embedded XML). For the XML file, units that have a corresponding EN16931 code (standard followed by Factur-X format) will be indicated with its relevant code. See mapping below of possible values and their corresponding code.
Possible values and corresponding EN16931 code (pursuant to the “Annexe 7” of the B2B external specifications for French e-invoicing, BT-130, allowed units of measure) | Unit | EN16931 code | |-------------------------|------| | unit | C62 | | hour | HUR | | day | DAY | | month | MON | | gram | GRM | | kilogram | KGM | | liter | LTR | | meter | MTR | | square_meter | MTK | | cubic_meter | MTQ | | ampere | AMP | | number_of_articles | NAR | | centimeter | CMT | | cubic_meter_per_hour | MQH | | gigajoule | GV | | gigawatt | A90 | | gigawatt_hour | GWH | | half_year | SAN | | joule | JOU | | kilojoule | KJO | | kilovar | KVR | | kilovolt_ampere_reactive_hour | K3 | | kilowatt | KWT | | kilowatt_hour | KWH | | megajoule | 3B | | megawatt | MAW | | megawatt_hour | MWH | | milligram | MGM | | milliliter | MLT | | millimeter | MMT | | minute | MIN | | pair | PR | | quarter | QAN | | second | SEC | | set | SET | | ton | TNE | | two_week | W4 | | watt_hour | WHR | | week | WEE | | year | ANN | | custom_input_text | ZZ |
- `unit_price` object, required - `value` string, required — represents price per unit of product or service sold. Decimals should be separated by a period “.” - `currency` string, required — represents the item’s currency. Currently, only value allowed is EUR. Format supported is a trigram following ISO 4217. - `vat_rate` string, required — represents the VAT rate applicable for that particular item. Written in decimals, separated by a period “.” For example, for a VAT of 10%, input is 0.1 - `vat_exemption_reason` 'N1' | 'N2' | 'N2.1' | 'N2.2' | 'N3' | 'N3.1' | 'N3.2' | 'N3.3' | 'N3.4' | 'N3.5' | 'N3.6' | 'N4' | 'N5' | 'N6' | 'N6.1' | 'N6.2' | 'N6.3' | 'N6.4' | 'N6.5' | 'N6.6' | 'N6.7' | 'N6.8' | 'N6.9' | 'N7' | 'S293B' | 'S262.1' | 'S259' | 'S283' | 'S261' | 'S262' | 'S263' | 'S19.1' | 'S4.1B' | 'S4.1A' | 'S4' | 'S13B' | 'S122' | 'S25' | 'S21' | 'S69' | 'S20' | 'S84.1.2' — Represents the VAT exemption reason when the item’s vat_rate is equal to 0. It is required for Italian organizations only, must be indicated for each item that has a VAT rate of 0 and the code must start with `N`. If VAT rate is not 0, this field should not be included. - `discount` object - `type` 'percentage' | 'absolute' — represents the type of the discount for that item. - `value` string — represents the rate or the absolute amount that will be discounted - `report_einvoicing` boolean — - For Italian organizations only - Non-Italian organizations should not include this attribute in the request. - Italian organizations must have e-invoicing activated to use this endpoint, no matter the value of the flag. - By default for an Italian organization that has e-invoicing activated on the Qonto app, if this field is not filled, this attribute is set to true and the invoice is automatically sent to Italian exchange system (Sistema di Interscambio, or SdI) as an XML e-invoice. If set to `false`, the invoice will not be sent to SdI. - Use the `GET` v2/client_invoices to retrieve its e-invoicing status under the attribute `einvoicing_status`. - `payment_reporting` object — - For Italian organizations only - Non-Italian organizations should not include this attribute in the request. - Object which relates to payment methods and conditions of the invoice. - `conditions` 'TP01' | 'TP02' | 'TP03', required — represents the payment conditions on the invoice. - `method` 'MP01' | 'MP02' | 'MP03' | 'MP04' | 'MP05' | 'MP06' | 'MP07' | 'MP08' | 'MP09' | 'MP10' | 'MP11' | 'MP12' | 'MP13' | 'MP14' | 'MP15' | 'MP16' | 'MP17' | 'MP18' | 'MP19' | 'MP20' | 'MP21' | 'MP22', required — represents the payment method of the invoice. - `welfare_fund` object — - For Italian organizations only - Non-Italian organizations should not include this attribute in the request. - Object which relates to pension contributions added to the total amount to pay, applicable in some cases. - This amount is a percentage added to the total amount of the invoice pre-taxes. - `type` 'TC01' | 'TC02' | 'TC03' | 'TC04' | 'TC05' | 'TC06' | 'TC07' | 'TC08' | 'TC09' | 'TC10' | 'TC11' | 'TC12' | 'TC13' | 'TC14' | 'TC15' | 'TC16' | 'TC17' | 'TC18' | 'TC19' | 'TC20' | 'TC21' | 'TC22', required — represents the welfare fund type. - `rate` string, required — represents the welfare fund rate applicable for the invoice. Written in decimals, separated by a period “.” For example, for a rate of 1%, input is 0.01, and for a rate of 10%, input is 0.1 - `withholding_tax` object — - Only for Italian organizations and Spanish freelancers - Other organizations should not include this attribute in the request. - Object which relates to an amount of tax paid by the client, rather than the supplier, for specific cases. - This amount is a percentage deducted from the total amount of the invoice after VAT application. - ES freelancers need to only fill the withholding_tax `rate` field with their IRPF. - `reason` 'RF01' | 'RF02' | 'RF03' | 'RF04' | 'RF05' | 'RF06', required — represents the reason the withholding tax. - `rate` string, required — represents the withholding tax rate applicable for the invoice. Written in decimals, separated by a period “.” For example, for a rate of 1%, input is 0.01 and for a rate of 10%, input is 0.1 - `payment_reason` string, required — represents the payment reason the withholding tax. - `stamp_duty_amount` string — - For Italian organizations only - Non-Italian organizations should not include this attribute in the request. - Represents an amount (2.00 EUR) applicable on invoices where VAT is excluded and the invoice has a value exceeding 77.47 EUR. ## Response `200` Returns the newly created client invoice. - object - `client_invoice` ClientInvoice, required - `id` string, uuid, required - `organization_id` string, uuid, required - `attachment_id` string, uuid — Attachment UUID corresponding to that particular invoice.
When creating the invoice (by calling the [POST /v2/client_invoices](https://api-doc.qonto.com/docs/business-api/740572a1dd6f7-create-a-client-invoice) endpoint), the attachment is generated **asynchronously**; which means that you have to wait ~10s and then call the [GET /v2/client_invoices/{id}](https://api-doc.qonto.com/docs/business-api/copd6wc7nwym8-show-client-invoice) endpoint to get the `attachment_id`.
This attribute enables you to get the invoice file by using the [GET /v2/attachments/{id}](https://api-doc.qonto.com/docs/business-api/345dace7b485b-show-attachment) endpoint. - `number` string, required - `purchase_order` string, required — Purchase order data added by the invoice’s initiator. - `status` 'draft' | 'unpaid' | 'paid' | 'canceled', required - `invoice_url` string, uri, required — URL of the invoice public page, accessible without authentication for 180 days after issuance, provided the invoice has not been canceled. - `contact_email` string, email, required — E-mail address of the invoice’s initiator. - `terms_and_conditions` string, required — The T&C data added by the invoice’s initiator. - `discount_conditions` string, nullable, required — Any discount for advance payment of the invoice. It is optional and is only for French organizations. - `late_payment_penalties` string, nullable, required — Late payment penalties applied in case of non-payment invoice. It is optional and is only for French organizations. - `legal_fixed_compensation` string, nullable, required — The legal fixed compensation applied in case late payment of the invoice. It is optional and is only for French organizations. - `header` string, required — The header text added by the credit note’s initiator. - `footer` string, required — The footer text added by the credit note’s initiator. - `currency` string, required - `total_amount` object, required — Total amount that needs to be paid by the client. - `value` string - `currency` string - `total_amount_cents` integer, required — Total amount in cents that needs to be paid by the client. - `vat_amount` object, required — VAT amount that is applicable to the invoice. - `value` string - `currency` string - `vat_amount_cents` integer, required — VAT amount in cents that is applicable to the invoice. - `issue_date` string, date, required — Date the initiator mentioned that the invoice was created. - `due_date` string, date, required — Payment’s deadline added by the initiator. - `performance_date` string, date, required — Date the initiator mentioned that the contents of the invoice were performed. - `created_at` string, date-time, required — Date the invoice was created. Note that this is a machine date. - `finalized_at` string, date-time, required — Date the invoice was transitioned from `Draft` to `Unpaid` status. - `paid_at` string, date-time, required — Date on which the invoice was paid. - `stamp_duty_amount` string, required - `items` DocumentItem[], required - `title` string - `description` string - `quantity` string - `unit` string - `unit_price` object — Amount of the price per unit. Note that an item can contain multiple units. The number of units is defined via `quantity`. - `value` string - `currency` string - `unit_price_cents` integer — Amount in cents of the price per unit. Note that an item can contain multiple units. The number of units is defined via `quantity`. - `vat_rate` string — VAT rate in decimal (0.1 for 10%) applicable to that particular item. - `vat_exemption_reason` 'N1' | 'N2' | 'N2.1' | 'N2.2' | 'N3' | 'N3.1' | 'N3.2' | 'N3.3' | 'N3.4' | 'N3.5' | 'N3.6' | 'N4' | 'N5' | 'N6' | 'N6.1' | 'N6.2' | 'N6.3' | 'N6.4' | 'N6.5' | 'N6.6' | 'N6.7' | 'N6.8' | 'N6.9' | 'N7' | 'S293B' | 'S262.1' | 'S259' | 'S283' | 'S261' | 'S262' | 'S263' | 'S19.1' | 'S4.1B' | 'S4.1A' | 'S4' | 'S13B' | 'S122' | 'S25' | 'S21' | 'S69' | 'S20' | 'S84.1.2' — Exemption reason - `discount` object - `type` 'percentage' | 'absolute' - `value` string — Discount rate or absolute amount. For percentage, the minimum value is 0.0001 (0.01%), and the maximum value is 1 (100%). For absolute value, the maximum is determined by Quantity * Unit Price. - `amount` object - `value` string - `currency` string - `total_vat` object — VAT amount that is applicable to that specific item. - `value` string - `currency` string - `total_vat_cents` integer — VAT amount in cents that is applicable to that specific item. - `total_amount` object — Amount that needs to be paid by the client for that specific item. - `value` string - `currency` string - `total_amount_cents` integer — Amount in cents that needs to be paid by the client for that specific item. - `subtotal` object - `value` string — Subtotal amount for the item without VAT. Quantity * Unit_price. - `currency` string - `subtotal_cents` integer — Subtotal amount in cents for the item without VAT. - `client` EmbeddedClient, required — Client that needs to pay the invoice. - `id` string, uuid - `name` string — Note that this attribute will be returned only if the client is a `company`. - `first_name` string — Note that this attribute will be returned only if the client is an `individual` or a `freelancer`. - `last_name` string — Note that this attribute will be returned only if the client is an `individual` or a `freelancer`. - `type` 'individual' | 'company' | 'freelancer' - `email` string, email - `vat_number` string - `tax_identification_number` string - `address` string - `city` string - `zip_code` string - `province_code` string — Province code of the client. It is required only for Italian organizations - `country_code` string - `recipient_code` string — Recipient code, so that the client can receive the e-invoice in his SdI portal. - `locale` string - `billing_address` ClientBillingAddress — Send either a `billing_address` object filled-in or individual root-level address fields (`address`, `city`, `zip_code`, `province_code`, `country_code`). When both are sent, `billing_address` takes precedence and overwrites root-level fields. - `street_address` string — Street address section of the billing address of the client (eg street, number, floor, door, etc). - `city` string — City on the billing address of the client - `zip_code` string — Zip code on the billing address of the client - `province_code` string — Province code of the client's billing address. It is required only for Italian organizations. - `country_code` string — Country code on the billing address of the client (ISO 3166 format) - `delivery_address` ClientDeliveryAddress - `street_address` string — Street address section of the delivery address of the client. (eg street, number, floor, door, etc) - `city` string — City on the delivery address of the client - `zip_code` string — Zip code on the delivery address of the client - `province_code` string — Province code of the client's delivery address. It is required only for Italian organizations - `country_code` string — Country code on the delivery address of the client (ISO 3166 format) - `payment_methods` object[], required - `beneficiary_name` string — Name of the beneficiary that will receive the invoice's payment. - `bic` string — Beneficiary’s International Bank Account Number. - `iban` string — Beneficiary account's Bank Identifier. - `type` 'transfer' — Invoice's payment method. - `credit_notes_ids` string[], required — If any credit notes are linked to the invoice, this represents the id of those credit notes. - `organization` EmbeddedInvoiceOrganization, required — Information of the organization at the time the document was issued. - `id` string, uuid - `legal_name` string - `legal_number` string - `legal_country` string - `address_line_1` string - `address_line_2` string - `address_zipcode` string - `address_city` string - `address_country` string - `company_leadership` string - `district_court` string - `commercial_register_number` string — Is available for French and German organizations and is optional. - For French organizations, it represents RCS number (numéro Registre du Commerce et des Sociétés) of an incorporated business. For example: RCS A 123 123 123. - For German organizations, it represents the organization's commercial register number (handelsregisternummer). For example: HRB 123455 B. - `vat_number` string - `tax_number` string - `legal_capital_share` object — Capital share of an incorporated business. It is optional and is only for French organizations. - `value` string - `currency` 'AED' | 'AUD' | 'BGN' | 'CAD' | 'CHF' | 'CNY' | 'CZK' | 'DKK' | 'EUR' | 'GBP' | 'GHS' | 'HKD' | 'HUF' | 'ILS' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RON' | 'RSD' | 'SAR' | 'SEK' | 'SGD' | 'TRY' | 'USD' | 'ZAR' | 'ZMW' - `transaction_type` 'goods' | 'services' | 'goods_and_services' — Type of transaction performed in the invoice. It is optional and is only for French organizations. - `vat_payment_condition` 'on_receipts' | 'compensated_for_sales' | 'exempt' — Business’ VAT elected payment condition (whether TVA is paid on receipt or on invoice emission). There are two allowed values: - `receipt` which stands for “sur les encaissements” in French; - `compensated_for_sales` which stands for “sur les débits” in French. It is optional and is only for French organizations. - `einvoicing_status` 'pending' | 'submitted' | 'declined' | 'approved' | 'not_delivered' | 'submission_failed' - `welfare_fund` object - `type` 'TC01' | 'TC02' | 'TC03' | 'TC04' | 'TC05' | 'TC06' | 'TC07' | 'TC08' | 'TC09' | 'TC10' | 'TC11' | 'TC12' | 'TC13' | 'TC14' | 'TC15' | 'TC16' | 'TC17' | 'TC18' | 'TC19' | 'TC20' | 'TC21' | 'TC22' - `rate` string - `withholding_tax` object — - Only applicable for Italian organizations and Spanish freelancers. - Object which relates to an amount of tax paid by the client, rather than the supplier, for specific cases. - This amount is a percentage deducted from the total amount of the invoice after VAT application. - The `rate` field specifies the percentage of tax and `amount` field specifies the total amount of the tax. - `reason` 'RF01' | 'RF02' | 'RF03' | 'RF04' | 'RF05' | 'RF06' - `rate` string - `payment_reason` string - `amount` string - `payment_reporting` object - `conditions` 'TP01' | 'TP02' | 'TP03' - `method` 'MP01' | 'MP02' | 'MP03' | 'MP04' | 'MP05' | 'MP06' | 'MP07' | 'MP08' | 'MP09' | 'MP10' | 'MP11' | 'MP12' | 'MP13' | 'MP14' | 'MP15' | 'MP16' | 'MP17' | 'MP18' | 'MP19' | 'MP20' | 'MP21' | 'MP22' ## Other responses - `400` — Returns a bad request error. - `401` — Returns an unauthorized error. - `403` — Returns a forbidden error. - `422` — Returns an unprocessable entity error. - `500` — Returns an internal server error. --- [API](https://skmtc.net/hiit-consulting-fr/apis/qonto.md) · [All operations](https://skmtc.net/hiit-consulting-fr/apis/qonto/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hiit-consulting-fr/qonto/revisions/25208d6f9deb/schema)