When your platform receives bills or purchase invoices, pushing them directly into Qonto saves your team from re-uploading files manually and keeps expense tracking centralised. In this guide, we will upload a supplier invoice file via the bulk endpoint and verify the response to confirm it was ingested successfully.
Example: A procurement platform forwards vendor invoices received by email directly into Qonto as soon as they arrive, ready for approval without any manual upload.
Prerequisites:
- A PDF invoice file ready to upload (max 10 MB).
- Scope:
supplier_invoice.write
Upload the invoice file
Send the PDF using POST /v2/supplier_invoices/bulk. You can upload the raw file binary or reference an existing attachment by its ID.Endpoint: Create supplier invoicesOAuth scope required: supplier_invoice.write.
Maximum 20 invoices per request. Each invoice requires a unique idempotency_key (UUID recommended) to prevent duplicate uploads. See Idempotent requests. This endpoint returns HTTP 200 even when individual invoices fail to process. Always inspect the errors array in the response body for each invoice when you receive a 200.Authentication failures still return 401, permission issues return 403, and server-side errors return 500.
You must provide either file or attachment_id for each invoice, not both. Including both will result in an error.
import uuid
import requests
BASE_URL = "https://thirdparty.qonto.com/v2"
headers = {"Authorization": "Bearer {your_access_token}"}
with open("./invoice.pdf", "rb") as f:
response = requests.post(
f"{BASE_URL}/supplier_invoices/bulk",
headers=headers,
data={
"supplier_invoices[][idempotency_key]": str(uuid.uuid4()),
"source": "integration",
},
files={
"supplier_invoices[][file]": ("invoice.pdf", f, "application/pdf"),
},
)
# Always 200 — check errors in body
result = response.json()
import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";
const BASE_URL = "https://thirdparty.qonto.com/v2";
const headers = { Authorization: "Bearer {your_access_token}" };
const fileBuffer = await readFile("./invoice.pdf");
const formData = new FormData();
formData.append(
"supplier_invoices[][file]",
new Blob([fileBuffer], { type: "application/pdf" }),
"invoice.pdf"
);
formData.append("supplier_invoices[][idempotency_key]", randomUUID());
formData.append("source", "integration");
const response = await fetch(`${BASE_URL}/supplier_invoices/bulk`, {
method: "POST",
headers, // Do NOT set Content-Type — fetch sets it automatically with the boundary
body: formData,
});
// Always 200 — check errors in body
const result = await response.json();
Check the response for errors
Inspect the response to confirm each invoice was processed successfully.supplier_invoices = result.get("supplier_invoices", [])
for invoice in supplier_invoices:
errors = invoice.get("errors", [])
if errors:
print(f"Failed: {errors}")
else:
print(f"Uploaded successfully: {invoice.get('id')}")
const supplierInvoices = result.supplier_invoices ?? [];
for (const invoice of supplierInvoices) {
if (invoice.errors?.length) {
console.error("Failed:", invoice.errors);
} else {
console.log(`Uploaded successfully: ${invoice.id}`);
}
}
| Code | Cause |
|---|
invalid | File too large or unsupported content type |
required | Missing idempotency_key |
limit_reached | More than 20 invoices in the request |
internal_server_error | Processing failed on Qonto’s side |
[Step 1] POST /supplier_invoices/bulk (file: sample_invoice.pdf)
HTTP status: 200
[Step 2] Check response
Uploaded successfully: 019d0705-xxxx-xxxx-xxxx-xxxxxxxxxxxx
We now have the supplier invoice uploaded to Qonto and queued for review. It will appear in the “Supplier invoices” section of the Qonto app with status to_review.
