Skip to main content
POST
/
v2
/
client_invoices
Create a client invoice
curl --request POST \
  --url https://thirdparty.qonto.com/v2/client_invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "client_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "issue_date": "2022-03-01",
  "due_date": "2023-12-25",
  "currency": "EUR",
  "payment_methods": {
    "iban": "<string>"
  },
  "items": [
    {
      "title": "<string>",
      "quantity": "0.5",
      "unit_price": {
        "value": "<string>",
        "currency": "<string>"
      },
      "vat_rate": "0.1",
      "description": "<string>",
      "unit": "meter",
      "vat_exemption_reason": "N1",
      "discount": {
        "type": "percentage",
        "value": "0.1"
      }
    }
  ],
  "upload_id": "4d5418bb-bd0d-4df4-865c-c07afab8bb48",
  "performance_date": "2023-12-25",
  "performance_start_date": "2022-03-01",
  "performance_end_date": "2022-03-31",
  "status": "draft",
  "number": "INV-2023-001",
  "purchase_order": "<string>",
  "terms_and_conditions": "<string>",
  "header": "This is an example.",
  "footer": "This is an example.",
  "settings": {
    "vat_number": "FR12345678",
    "company_leadership": "Jan Mueller",
    "district_court": "Munich",
    "commercial_register_number": "HRB12345B",
    "tax_number": "123/123/1234",
    "legal_capital_share": {
      "value": "10000.00",
      "currency": "EUR"
    },
    "transaction_type": "goods",
    "vat_payment_condition": "on_receipts",
    "discount_conditions": "Pas d’escompte accordé pour paiement anticipé.",
    "late_payment_penalties": "En cas de non-paiement à la date d'échéance, des pénalités calculées à trois fois le taux d’intérêt légal seront appliquées.",
    "legal_fixed_compensation": "Tout retard de paiement entraînera une indemnité forfaitaire pour frais de recouvrement de 40€."
  },
  "report_einvoicing": true,
  "payment_reporting": {
    "conditions": "TP01",
    "method": "MP01"
  },
  "welfare_fund": {
    "type": "TC01",
    "rate": "0.0001"
  },
  "withholding_tax": {
    "reason": "RF01",
    "rate": "0.01",
    "payment_reason": "L1"
  },
  "stamp_duty_amount": "1.00",
  "discount": {
    "type": "percentage",
    "value": "0.1"
  }
}
EOF
{
  "client_invoice": {
    "id": "4d5418bb-bd0d-4df4-865c-c07afab8bb48",
    "organization_id": "4d5418bb-bd0d-4df4-865c-c07afab8bb48",
    "number": "INV001",
    "purchase_order": "<string>",
    "status": "paid",
    "invoice_url": "https://pay.qonto.com/invoices/00000000-0000-0000-0000-000000000000",
    "contact_email": "[email protected]",
    "terms_and_conditions": "This is an example.",
    "discount_conditions": "Pas d’escompte accordé pour paiement anticipé.",
    "late_payment_penalties": "En cas de non-paiement à la date d'échéance, des pénalités calculées à trois fois le taux d’intérêt légal seront appliquées.",
    "legal_fixed_compensation": "Tout retard de paiement entraînera une indemnité forfaitaire pour frais de recouvrement de 40€.",
    "header": "This is an example.",
    "footer": "This is an example.",
    "currency": "EUR",
    "total_amount": {
      "value": "12.52",
      "currency": "EUR"
    },
    "total_amount_cents": 1252,
    "vat_amount": {
      "value": "0.51",
      "currency": "EUR"
    },
    "vat_amount_cents": 51,
    "issue_date": "2022-03-01",
    "due_date": "2022-03-01",
    "performance_date": "2022-03-01",
    "performance_start_date": "2022-03-01",
    "performance_end_date": "2022-03-31",
    "created_at": "2022-03-04T17:58:30+02:00",
    "finalized_at": "2022-03-04T17:58:30+02:00",
    "paid_at": "2022-03-04T17:58:30+02:00",
    "stamp_duty_amount": "1.00",
    "items": [
      {
        "title": "Plastic tables",
        "description": "Plastic tables for McDonald’s restaurants",
        "quantity": "1.5",
        "unit": "meter",
        "unit_price": {
          "value": "10.0",
          "currency": "EUR"
        },
        "unit_price_cents": 1000,
        "vat_rate": "0.1",
        "vat_exemption_reason": "N1",
        "discount": {
          "type": "percentage",
          "value": "0.1",
          "amount": {
            "value": "120",
            "currency": "EUR"
          }
        },
        "total_vat": {
          "value": "120",
          "currency": "EUR"
        },
        "total_vat_cents": 12000,
        "total_amount": {
          "value": "300.50",
          "currency": "EUR"
        },
        "total_amount_cents": 30050,
        "subtotal": {
          "value": "120",
          "currency": "EUR"
        },
        "subtotal_cents": 12000
      }
    ],
    "client": {
      "id": "33v418bb-bd0d-4df4-865c-c07afab8bb48",
      "name": "McDonald's",
      "first_name": "Jane",
      "last_name": "Doe",
      "type": "individual",
      "email": "[email protected]",
      "vat_number": "FR32123456789",
      "tax_identification_number": "123456789",
      "address": "1 place de l’Opéra",
      "city": "Paris",
      "zip_code": "75009",
      "province_code": "<string>",
      "country_code": "fr",
      "recipient_code": "<string>",
      "locale": "fr",
      "billing_address": {
        "street_address": "123 Main Street",
        "city": "Paris",
        "zip_code": "75009",
        "province_code": "<string>",
        "country_code": "FR"
      },
      "delivery_address": {
        "street_address": "123 Main Street",
        "city": "Paris",
        "zip_code": "75009",
        "province_code": "<string>",
        "country_code": "FR"
      }
    },
    "payment_methods": [
      {
        "beneficiary_name": "John Doe",
        "bic": "ABCDEFG1XXX",
        "iban": "FR1420041010050500013M02606",
        "type": "transfer"
      }
    ],
    "credit_notes_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "organization": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "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": "Jan Mueller",
      "district_court": "Munich",
      "commercial_register_number": "HRB12345B",
      "vat_number": "FR123456789",
      "tax_number": "123/123/1234",
      "legal_capital_share": {
        "value": "10000.00",
        "currency": "EUR"
      },
      "transaction_type": "goods",
      "vat_payment_condition": "on_receipts"
    },
    "invoice_type": "standard",
    "attachment_id": "4d5418bb-bd0d-4df4-865c-c07afab8bb48",
    "discount": {
      "type": "percentage",
      "value": "0.1",
      "amount": {
        "value": "10.00",
        "currency": "EUR"
      }
    },
    "einvoicing_status": "pending",
    "welfare_fund": {
      "type": "TC01",
      "rate": "0.0001"
    },
    "withholding_tax": {
      "reason": "RF01",
      "rate": "0.01",
      "payment_reason": "L1",
      "amount": "1.00"
    },
    "payment_reporting": {
      "conditions": "TP01",
      "method": "MP01"
    },
    "einvoicing_lifecycle_events": [
      {
        "status_code": 200,
        "reason": "DOUBLE FACTURE",
        "reason_message": "I already received this invoice",
        "timestamp": "2024-12-04T11:05:16.4497Z"
      }
    ]
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authorization header: Bearer <token>, where <token> is the access token received from the authorization server at the end of the OAuth 2.0 flow.

Headers

​
X-Qonto-Staging-Token
string

Required only for Sandbox API requests; to get one, please sign up to the Developer Portal.

Body

application/json
​
client_id
string<uuid>
required

The ID of the associated client. The client is validated against the business rules of the invoicing domain. In case of getting a validation error related to a field in the customer, you will need to issue a request to update the customer itself and then try to re-create the invoice itself. This is because a client can be used across different domains - client creation performs only minimal validations on the client and then it is up to each domain (for example, invoicing) to apply their own business rules on top of that client. More information can be found in the docs for creating a client.

​
issue_date
string<date>
required
Example:

"2022-03-01"

​
due_date
string<date>
required

Payment deadline that is added by the initiator. The format should be YYYY-MM-DD

​
currency
string
required

Currency for the total amount of the invoice. Currently, only value allowed is EUR. Trigram following ISO 4217

Example:

"EUR"

​
payment_methods
object
required

Payment method details for the invoice.

​
items
object[]
required
​
upload_id
string<uuid>

Optional ID of a previously uploaded file to attach to this invoice. The upload must have been created using the POST /v2/client_invoices/uploads endpoint.

Example:

"4d5418bb-bd0d-4df4-865c-c07afab8bb48"

​
performance_date
string<date>
deprecated

DEPRECATED: This field is deprecated. Please use performance_start_date and performance_end_date instead.

The performance date represents when the job or service is expected to be completed by the client. Date the initiator has issued or shared the invoice as legally viable. The format should be YYYY-MM-DD

​
performance_start_date
string<date>

Start date of the performance period for the invoice. The format should be YYYY-MM-DD.

The performance period defines the date range during which the job or service is expected to be completed by the client. This field marks the beginning of that period and can be used together with performance_end_date to create a flexible date range instead of a single fixed date.

Validation rules:

  • Required if performance_end_date is provided
  • Must be less than or equal to performance_end_date when both are provided

Fallback behavior:

  • If not provided, the system will use the deprecated performance_date value as fallback
  • If provided, this value will override the deprecated performance_date field
Example:

"2022-03-01"

​
performance_end_date
string<date>

End date of the performance period for the invoice. The format should be YYYY-MM-DD.

This field defines the end of the performance date range, allowing clients to complete the job or service anytime between performance_start_date and performance_end_date. When used together with performance_start_date, it creates a flexible time window rather than requiring completion on a specific date.

Validation rules:

  • Optional field
  • When provided, performance_start_date becomes required
  • Must be greater than or equal to performance_start_date
Example:

"2022-03-31"

​
status
enum<string>

Invoice's status. If not filled, unpaid will be automatically propertyd to the invoice.

Available options:
draft,
unpaid
​
number
string

Invoice's number. Must be unique within the organization and is:

  • required if automatic numbering is disabled for the authenticated organization (default setting);
  • optional if automatic numbering is enabled for the authenticated organization. However, if provided, it will be used as the invoice's number.
Maximum string length: 40
Example:

"INV-2023-001"

​
purchase_order
string

Purchase order data added by the invoice’s initiator.

Maximum string length: 40
​
terms_and_conditions
string

Additional notes added by the invoice’s initiator.

Maximum string length: 525
​
header
string
Example:

"This is an example."

​
footer
string
Example:

"This is an example."

​
settings
object

This collection of properties can be optionally used to temporarily override some of the organization's properties for this one invoice.

​
report_einvoicing
boolean
  • For Italian organizations only
  • Non-Italian organizations should not include this property 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 property 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 property einvoicing_status.
​
payment_reporting
object
  • For Italian organizations only
  • Non-Italian organizations should not include this property in the request.
  • Object which relates to payment methods and conditions of the invoice.
​
welfare_fund
object
  • For Italian organizations only
  • Non-Italian organizations should not include this property 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.
​
withholding_tax
object
  • Only for Italian organizations and Spanish freelancers
  • Other organizations should not include this property 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.
​
stamp_duty_amount
string
  • For Italian organizations only
  • Non-Italian organizations should not include this property 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.
Required string length: 4 - 15
Example:

"1.00"

​
discount
object

Global discount applied to the entire invoice. This discount is applied to the sum of all items (after item-level discounts, if any).

Response

Returns the client invoice created.

​
client_invoice
object
required