v2

latestOpenAPI 3.0.3raw.githubusercontent.com2025-01-245593419.2 KB

Client Invoices

Create a client invoice

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.

post/v2/client_invoices

Headers

X-Qonto-Staging-Tokenstring

Required only for Sandbox API requests; to get one, please submit the following form: https://getqonto.atlassian.net/servicedesk/customer/portal/5/group/47/create/143.

Request body

client_idstring uuid required

issue_datestring date required

performance_datestring date

represents the date the initiator has issued or shared the invoice as legally viable. The format should be YYYY-MM-DD

due_datestring 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.

numberstring required

represents the invoice’s number.

purchase_orderstring

represents the purchase order data added by the invoice’s initiator.

terms_and_conditionsstring

represents additional notes added by the invoice’s initiator.

headerstring

footerstring

currencystring required

represents the invoice’s currency for the total amount of the invoice. Currently, only value allowed is EUR. Trigram following ISO 4217

report_einvoicingboolean

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.

stamp_duty_amountstring

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.

Example request

{
  "issue_date": "2022-03-01",
  "number": "INV-2023-001",
  "header": "This is an example.",
  "footer": "This is an example.",
  "currency": "EUR",
  "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€."
  },
  "items": [
    {
      "quantity": "0.5",
      "unit": "meter",
      "vat_rate": "0.1",
      "vat_exemption_reason": "N1",
      "discount": {
        "type": "percentage",
        "value": "0.1"
      }
    }
  ],
  "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"
}

Response

Returns the newly created client invoice.

Example response

{
  "client_invoice": {
    "id": "4d5418bb-bd0d-4df4-865c-c07afab8bb48",
    "organization_id": "4d5418bb-bd0d-4df4-865c-c07afab8bb48",
    "attachment_id": "4d5418bb-bd0d-4df4-865c-c07afab8bb48",
    "number": "INV001",
    "status": "paid",
    "invoice_url": "https://pay.qonto.com/invoices/00000000-0000-0000-0000-000000000000",
    "contact_email": "contact@qonto.com",
    "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",
    "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",
        "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": "client@qonto.com",
      "vat_number": "FR32123456789",
      "tax_identification_number": "123456789",
      "address": "1 place de l’Opéra",
      "city": "Paris",
      "zip_code": "75009",
      "country_code": "fr",
      "locale": "fr",
      "billing_address": {
        "street_address": "123 Main Street",
        "city": "Paris",
        "zip_code": "75009",
        "country_code": "FR"
      },
      "delivery_address": {
        "street_address": "123 Main Street",
        "city": "Paris",
        "zip_code": "75009",
        "country_code": "FR"
      }
    },
    "payment_methods": [
      {
        "beneficiary_name": "John Doe",
        "bic": "ABCDEFG1XXX",
        "iban": "FR1420041010050500013M02606",
        "type": "transfer"
      }
    ],
    "organization": {
      "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"
    },
    "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"
    }
  }
}