List client invoices

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.

Query Parameters

filter[status]

enum<string>[]

Invoices can be filtered by their status:

draft: the invoice was created but not validated. The invoice still needs to be validated to be paid.
unpaid: the invoice was created and validated. The invoice is ready to be paid.
canceled: the invoice was created but canceled by the initiator. The invoice it is not ready to be paid.
paid: the invoice was created, forwarded to the client, and successfully paid.

To filter by multiple statuses, use a comma-separated list.

Available options:

draft,

unpaid,

paid,

canceled

filter[created_at_from]

string<date-time>

Invoices can be filtered by their created_at property. This filter can be used in combination with the created_at_to query parameter to get invoices created within a specific timeframe. Please use a valid date time format (ISO 8601 for instance).

Example:

"2022-02-01T12:01:02Z"

filter[created_at_to]

string<date-time>

Invoices can be filtered by their created_at property. This filter can be used in combination with the created_at_from query parameter to get invoices created within a specific timeframe. Please use a valid date time format (ISO 8601 for instance).

Example:

"2022-04-23T16:23:00Z"

filter[updated_at_from]

string<date-time>

Invoices can be filtered by their updated_at property. This filter can be used in combination with the updated_at_to query parameter to get invoices updated within a specific timeframe. Please use a valid date time format (ISO 8601 for instance).

Example:

"2022-02-01T12:01:02Z"

filter[updated_at_to]

string<date-time>

Invoices can be filtered by their updated_at property. This filter can be used in combination with the updated_at_from query parameter to get invoices updated within a specific timeframe. Please use a valid date time format (ISO 8601 for instance).

Example:

"2022-04-23T16:23:00Z"

exclude_imported

boolean

default:true

Controls whether imported invoices should be excluded from the results.

true (default): Excludes invoices that have been imported.
false: Includes all invoices, including imported ones.

Note: By default, imported invoices are excluded. To retrieve imported invoices, explicitly set this parameter to false.

Example:

false

page

integer

Returned page (cf. Pagination).

Example:

1

per_page

integer

default:1

Number of invoices per page (cf. Pagination).

Required range: x >= 100

sort_by

enum<string>

default:created_at:desc

Invoices can be sorted by their created_at property in 2 possible orders: asc (Ascending) / desc (Descending).

Available options:

created_at:desc,

created_at:asc

Response

Returns the list of client invoices.

client_invoices

object[]

Show child attributes

client_invoices.id

string<uuid>

required

Example:

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

client_invoices.organization_id

string<uuid>

required

Example:

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

client_invoices.number

string

required

Example:

"INV001"

client_invoices.purchase_order

string

required

Purchase order data added by the invoice’s initiator.

client_invoices.status

enum<string>

required

Available options:

draft,

unpaid,

paid,

canceled

Example:

"paid"

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

Example:

"https://pay.qonto.com/invoices/00000000-0000-0000-0000-000000000000"

client_invoices.contact_email

string<email>

required

E-mail address of the invoice’s initiator.

Example:

"[email protected]"

client_invoices.terms_and_conditions

string

required

The T&C data added by the invoice’s initiator.

Example:

"This is an example."

client_invoices.discount_conditions

string | null

required

Any discount for advance payment of the invoice. It is optional and is only for French organizations.

Example:

"Pas d’escompte accordé pour paiement anticipé."

client_invoices.late_payment_penalties

string | null

required

Late payment penalties applied in case of non-payment invoice. It is optional and is only for French organizations.

Example:

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

client_invoices.legal_fixed_compensation

string | null

required

The legal fixed compensation applied in case late payment of the invoice. It is optional and is only for French organizations.

Example:

"Tout retard de paiement entraînera une indemnité forfaitaire pour frais de recouvrement de 40€."

client_invoices.header

string

required

The header text added by the credit note’s initiator.

Example:

"This is an example."

client_invoices.footer

string

required

The footer text added by the credit note’s initiator.

Example:

"This is an example."

client_invoices.currency

string

required

Example:

"EUR"

client_invoices.total_amount

object

required

Total amount that needs to be paid by the client.

Show child attributes

client_invoices.total_amount.value

string

Example:

"12.52"

client_invoices.total_amount.currency

string

Example:

"EUR"

client_invoices.total_amount_cents

integer

required

Total amount in cents that needs to be paid by the client.

Example:

1252

client_invoices.vat_amount

object

required

VAT amount that is applicable to the invoice.

Show child attributes

client_invoices.vat_amount.value

string

Example:

"0.51"

client_invoices.vat_amount.currency

string

Example:

"EUR"

client_invoices.vat_amount_cents

integer

required

VAT amount in cents that is applicable to the invoice.

Example:

51

client_invoices.issue_date

string<date>

required

Date the initiator mentioned that the invoice was created.

Example:

"2022-03-01"

client_invoices.due_date

string<date>

required

Payment’s deadline added by the initiator.

Example:

"2022-03-01"

client_invoices.performance_date

string<date>

required

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 was completed by the client. Date the initiator mentioned that the contents of the invoice were performed.

Example:

"2022-03-01"

client_invoices.performance_start_date

string<date>

required

Start date of the performance period mentioned by the initiator for the invoice contents.

The performance period defines the date range during which the job or service was 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.

Example:

"2022-03-01"

client_invoices.performance_end_date

string<date>

required

End date of the performance period mentioned by the initiator for the invoice contents.

This field defines the end of the performance date range, allowing the work or service to have been completed anytime between performance_start_date and performance_end_date. When used together with performance_start_date, it creates a flexible time window rather than specifying completion on a single specific date.

Example:

"2022-03-31"

client_invoices.created_at

string<date-time>

required

Date the invoice was created. Note that this is a machine date.

Example:

"2022-03-04T17:58:30+02:00"

client_invoices.finalized_at

string<date-time>

required

Date the invoice was transitioned from Draft to Unpaid status.

Example:

"2022-03-04T17:58:30+02:00"

client_invoices.paid_at

string<date-time>

required

Date on which the invoice was paid.

Example:

"2022-03-04T17:58:30+02:00"

client_invoices.stamp_duty_amount

string

required

Required string length: 4 - 15

Example:

"1.00"

client_invoices.items

object[]

required

Show child attributes

client_invoices.items.title

string

Example:

"Plastic tables"

client_invoices.items.description

string

Example:

"Plastic tables for McDonald’s restaurants"

client_invoices.items.quantity

string

Example:

"1.5"

client_invoices.items.unit

string

Example:

"meter"

client_invoices.items.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.

Show child attributes

client_invoices.items.unit_price.value

string

Example:

"10.0"

client_invoices.items.unit_price.currency

string

Example:

"EUR"

client_invoices.items.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.

Example:

1000

client_invoices.items.vat_rate

string

VAT rate in decimal (0.1 for 10%) applicable to that particular item.

Example:

"0.1"

client_invoices.items.vat_exemption_reason

enum<string>

Exemption reason

Available options:

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

client_invoices.items.discount

object

Show child attributes

client_invoices.items.discount.type

enum<string>

Available options:

percentage,

absolute

Example:

"percentage"

client_invoices.items.discount.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.

Example:

"0.1"

client_invoices.items.discount.amount

object

Show child attributes

client_invoices.items.discount.amount.value

string

Example:

"120"

client_invoices.items.discount.amount.currency

string

Example:

"EUR"

client_invoices.items.total_vat

object

VAT amount that is applicable to that specific item.

Show child attributes

client_invoices.items.total_vat.value

string

Example:

"120"

client_invoices.items.total_vat.currency

string

Example:

"EUR"

client_invoices.items.total_vat_cents

integer

VAT amount in cents that is applicable to that specific item.

Example:

12000

client_invoices.items.total_amount

object

Amount that needs to be paid by the client for that specific item.

Show child attributes

client_invoices.items.total_amount.value

string

Example:

"300.50"

client_invoices.items.total_amount.currency

string

Example:

"EUR"

client_invoices.items.total_amount_cents

integer

Amount in cents that needs to be paid by the client for that specific item.

Example:

30050

client_invoices.items.subtotal

object

Show child attributes

client_invoices.items.subtotal.value

string

Subtotal amount for the item without VAT. Quantity * Unit_price.

Example:

"120"

client_invoices.items.subtotal.currency

string

Example:

"EUR"

client_invoices.items.subtotal_cents

integer

Subtotal amount in cents for the item without VAT.

Example:

12000

client_invoices.client

object

required

Client that needs to pay the invoice.

Show child attributes

client_invoices.client.id

string<uuid>

Example:

"33v418bb-bd0d-4df4-865c-c07afab8bb48"

client_invoices.client.name

string

Note that this property will be returned only if the client is a company.

Example:

"McDonald's"

client_invoices.client.first_name

string

Note that this property will be returned only if the client is an individual or a freelancer.

Example:

"Jane"

client_invoices.client.last_name

string

Note that this property will be returned only if the client is an individual or a freelancer.

Example:

"Doe"

client_invoices.client.type

enum<string>

Available options:

individual,

company,

freelancer

Example:

"individual"

client_invoices.client.email

string<email>

Example:

"[email protected]"

client_invoices.client.vat_number

string

Example:

"FR32123456789"

client_invoices.client.tax_identification_number

string

Example:

"123456789"

client_invoices.client.address

string

Example:

"1 place de l’Opéra"

client_invoices.client.city

string

Example:

"Paris"

client_invoices.client.zip_code

string

Example:

"75009"

client_invoices.client.province_code

string

Province code of the client. It is required only for Italian organizations

client_invoices.client.country_code

string

Example:

"fr"

client_invoices.client.recipient_code

string

Recipient code, so that the client can receive the e-invoice in his SdI portal.

client_invoices.client.locale

string

Example:

"fr"

client_invoices.client.billing_address

object

Billing address of the client, which will be reflected on the invoice. Stores the same data as the root-level fields address fields (address, city, zip_code, province_code, country_code). 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.

Show child attributes

client_invoices.client.billing_address.street_address

string

Street address section of the billing address of the client (eg street, number, floor, door, etc).

Maximum string length: 250

Example:

"123 Main Street"

client_invoices.client.billing_address.city

string

City on the billing address of the client

Maximum string length: 50

Example:

"Paris"

client_invoices.client.billing_address.zip_code

string

Zip code on the billing address of the client

Maximum string length: 20

Example:

"75009"

client_invoices.client.billing_address.province_code

string

Province code of the client's billing address. It is required only for Italian organizations.

Maximum string length: 2

client_invoices.client.billing_address.country_code

string

Country code on the billing address of the client (ISO 3166 format)

Maximum string length: 2

Example:

"FR"

client_invoices.client.delivery_address

object

Delivery address of the client. Stores the same data as the root-level fields address fields (address, city, zip_code, province_code, country_code).

Show child attributes

client_invoices.client.delivery_address.street_address

string

Street address section of the delivery address of the client. (eg street, number, floor, door, etc)

Maximum string length: 250

Example:

"123 Main Street"

client_invoices.client.delivery_address.city

string

City on the delivery address of the client

Maximum string length: 50

Example:

"Paris"

client_invoices.client.delivery_address.zip_code

string

Zip code on the delivery address of the client

Maximum string length: 20

Example:

"75009"

client_invoices.client.delivery_address.province_code

string

Province code of the client's delivery address. It is required only for Italian organizations

Maximum string length: 2

client_invoices.client.delivery_address.country_code

string

Country code on the delivery address of the client (ISO 3166 format)

Maximum string length: 2

Example:

"FR"

client_invoices.payment_methods

object[]

required

Show child attributes

client_invoices.payment_methods.beneficiary_name

string

Name of the beneficiary that will receive the invoice's payment.

Example:

"John Doe"

client_invoices.payment_methods.bic

string

Beneficiary’s International Bank Account Number.

Example:

"ABCDEFG1XXX"

client_invoices.payment_methods.iban

string

Beneficiary account's Bank Identifier.

Example:

"FR1420041010050500013M02606"

client_invoices.payment_methods.type

enum<string>

Invoice's payment method.

Available options:

transfer

Example:

"transfer"

client_invoices.credit_notes_ids

string<uuid>[]

required

If any credit notes are linked to the invoice, this represents the id of those credit notes.

client_invoices.organization

object

required

Information of the organization at the time the document was issued.

Show child attributes

client_invoices.organization.id

string<uuid>

client_invoices.organization.legal_name

string

client_invoices.organization.legal_number

string

client_invoices.organization.legal_country

string

client_invoices.organization.address_line_1

string

client_invoices.organization.address_line_2

string

client_invoices.organization.address_zipcode

string

client_invoices.organization.address_city

string

client_invoices.organization.address_country

string

client_invoices.organization.company_leadership

string

Example:

"Jan Mueller"

client_invoices.organization.district_court

string

Example:

"Munich"

client_invoices.organization.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.

Example:

"HRB12345B"

client_invoices.organization.vat_number

string

Example:

"FR123456789"

client_invoices.organization.tax_number

string

Example:

"123/123/1234"

Capital share of an incorporated business. It is optional and is only for French organizations.

Show child attributes

Maximum string length: 12

Example:

"10000.00"

Available options:

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

Example:

"EUR"

client_invoices.organization.transaction_type

enum<string>

Type of transaction performed in the invoice. It is optional and is only for French organizations.

Available options:

goods,

services,

goods_and_services

Example:

"goods"

client_invoices.organization.vat_payment_condition

enum<string>

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.

Available options:

on_receipts,

compensated_for_sales,

exempt

Example:

"on_receipts"

client_invoices.invoice_type

enum<string>

required

Available options:

standard,

deposit,

balance

Example:

"standard"

client_invoices.attachment_id

string<uuid>

Attachment UUID corresponding to that particular invoice.
When creating the invoice (by calling the POST /v2/client_invoices endpoint), the attachment is generated asynchronously; which means that you have to wait ~10s and then call the GET /v2/client_invoices/{id} endpoint to get the attachment_id.
This property enables you to get the invoice file by using the GET /v2/attachments/{id} endpoint.

Example:

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

client_invoices.discount

object

Global discount that was applied to the invoice.

Show child attributes

client_invoices.discount.type

enum<string>

Type of the discount applied.

Available options:

percentage,

absolute

Example:

"percentage"

client_invoices.discount.value

string

Rate or absolute amount that was discounted.

Example:

"0.1"

client_invoices.discount.amount

object

The calculated discount amount that was deducted from the invoice.

Show child attributes

client_invoices.discount.amount.value

string

Example:

"10.00"

client_invoices.discount.amount.currency

string

Example:

"EUR"

client_invoices.einvoicing_status

enum<string>

Available options:

pending,

submitted,

declined,

approved,

not_delivered,

submission_failed

client_invoices.welfare_fund

object

Show child attributes

client_invoices.welfare_fund.type

enum<string>

Available options:

TC01,

TC02,

TC03,

TC04,

TC05,

TC06,

TC07,

TC08,

TC09,

TC10,

TC11,

TC12,

TC13,

TC14,

TC15,

TC16,

TC17,

TC18,

TC19,

TC20,

TC21,

TC22

Example:

"TC01"

client_invoices.welfare_fund.rate

string

Required string length: 4 - 6

Example:

"0.0001"

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

Show child attributes

client_invoices.withholding_tax.reason

enum<string>

Available options:

RF01,

RF02,

RF03,

RF04,

RF05,

RF06

Example:

"RF01"

client_invoices.withholding_tax.rate

string

Required string length: 4 - 6

Example:

"0.01"

client_invoices.withholding_tax.payment_reason

string

Required string length: 1 - 2

Example:

"L1"

client_invoices.withholding_tax.amount

string

Example:

"1.00"

client_invoices.payment_reporting

object

Show child attributes

client_invoices.payment_reporting.conditions

enum<string>

Available options:

TP01,

TP02,

TP03

Example:

"TP01"

client_invoices.payment_reporting.method

enum<string>

Available options:

MP01,

MP02,

MP03,

MP04,

MP05,

MP06,

MP07,

MP08,

MP09,

MP10,

MP11,

MP12,

MP13,

MP14,

MP15,

MP16,

MP17,

MP18,

MP19,

MP20,

MP21,

MP22

Example:

"MP01"

client_invoices.einvoicing_lifecycle_events

object[]

Array of lifecycle events related to the e-invoicing process

Show child attributes

client_invoices.einvoicing_lifecycle_events.status_code

enum<integer>

Status code of the operation. - 200: Déposée (Submitted) - 201: Emise par la plateforme (Issued by the platform) - 202: Reçue de la plateforme (Received from the platform) - 203: Mise à disposition (Made available) - 204: Prise en charge (Taken over) - 205: Approuvée (Approved) - 206: Approuvée partiellement (Partially approved) - 207: En litige (In dispute) - 208: Suspendue (Suspended) - 209: Complétée (Completed) - 210: Refusée (Refused) - 211: Paiement transmis (Payment sent) - 212: Encaissée (Collected) - 213: Rejetée (Rejected) - 214: Visée (Vised)

Available options:

200,

201,

202,

203,

204,

205,

206,

207,

208,

209,

210,

211,

212,

213,

214

Example:

200

client_invoices.einvoicing_lifecycle_events.reason

string

The reason label associated with a given event

Example:

"DOUBLE FACTURE"

client_invoices.einvoicing_lifecycle_events.reason_message

string

The reason message associated with a given event (comment provided by the user generating the event)

Example:

"I already received this invoice"

client_invoices.einvoicing_lifecycle_events.timestamp

string<date-time>

The timestamp of the event

Example:

"2024-12-04T11:05:16.4497Z"

Business API

Onboarding API

List client invoices

Authorizations

Headers

Query Parameters

Response