Skip to main content

Request a fee export

Requests the generation of a CSV file with the requester's fees, for all accounts or for a single account. The file is generated in the background: the response returns the export key, and the invoice_export webhook notifies you when the file is ready.

Endpoint​

ENDPOINT
/billing/invoices/exports
METHOD
POST
STATUS
201

Authentication​

Requires a signed request. See Authentication. The requester is the one whose credential signs the request.

Request body​

All fields are optional. An empty body ({}) exports all of the requester's fees, subject to the size rule below.

FieldTypeRequiredDescriptionSize
start_datestringNoStart date of the period, in yyyy-mm-dd format, inclusive.10
end_datestringNoEnd date of the period, in yyyy-mm-dd format, inclusive. Cannot be earlier than start_date.10
payment_methodstringNoPayment method of the fee. payment_method enumerator—
statusstringNoFee status. status enumerator—
billing_typesarrayNoFee types (billing_type) to include. Empty includes all.—
owner_document_numberstringNoCPF or CNPJ of the account holder, digits only. Exports the fees of every account of that holder.—
account_numberstringNoAccount number, without the check digit.—
owner_namestringNoBeginning of the holder's name. The export includes the fees of the first 50 accounts returned by the holder name filter.—
account_keyuuidNoAccount key, to export the fee statement of a single account. Cannot be combined with the three fields above.36

Size rule​

  • Period of up to 31 days, counting both ends: the request is always accepted.
  • Period longer than 31 days, or without start_date and end_date: the request is accepted if the requester (or the account, when account_key is sent) has up to 200,000 fees in the period, counted without the other filters. Above that, the response is 422 BLL000136 and no export is created. Choose a shorter period.

Exports in progress​

  • A request with the same filters as another export still in progress does not create a new export: the response returns the existing one, with already_in_flight: true.
  • Each requester can have up to 20 exports in progress (pending or processing). The 21st receives 422 BLL000134.
{
"start_date": "2026-09-01",
"end_date": "2026-09-30",
"payment_method": "bank_slip",
"status": "open",
"billing_types": ["account_maintenance"],
"owner_document_number": "96969879003"
}

Response​

FieldTypeDescription
invoice_export_keyuuidExport key. Use it to query the export.
statusstringExport status. Export status enumerator
filtersobjectNormalized export filters: every body field, with null for those not sent.
row_countintegerNumber of fees already written to the file. Final only in done.
created_atstringDate and time of the request.
finished_atstringDate and time the file became ready. null until done.
expires_atstringDate and time until which the file can be downloaded. null until done.
file_namestringAlways null in this response.
download_urlstringAlways null in this response. The link is generated when the export is queried.
already_in_flightbooleantrue when the response is an export in progress with the same filters.
{
"invoice_export_key": "7a9c0a5e-1b2f-4c3d-9e8f-0123456789ab",
"status": "pending",
"filters": {
"start_date": "2026-09-01",
"end_date": "2026-09-30",
"payment_method": "bank_slip",
"status": "open",
"billing_types": ["account_maintenance"],
"owner_document_number": "96969879003",
"account_number": null,
"owner_name": null,
"account_key": null
},
"row_count": 0,
"created_at": "2026-10-15T14:03:11",
"finished_at": null,
"expires_at": null,
"file_name": null,
"download_url": null,
"already_in_flight": false
}

Errors​

StatusCodeDescription
400QIT000001Body out of format: unknown field, wrong type or account_key without 36 characters.
400BLL000096Date not in yyyy-mm-dd format, or end_date earlier than start_date.
400BLL000043status not in the enumerator.
400BLL000130payment_method not in the enumerator.
400BLL000137account_key sent together with owner_document_number, account_number or owner_name.
404BLL000111One of the billing_types does not exist.
404BLL000058account_key is not an account of the requester.
422BLL000134The requester already has 20 exports in progress. Wait for one of them to finish.
422BLL000136Period longer than 31 days with more than 200,000 fees. Choose a shorter period.

The error body follows the standard format (title, description, translation, code). The table above lists the codes of this endpoint; platform-wide errors, such as QIT000001, are in the common errors of the BaaS error catalog.

Enumerators​

payment_method enumerator​

ValueDescription
account_debitDebit from the holder's account.
centralizing_account_debitDebit from the requester's centralizing account.
bank_slipCharged by bank slip (boleto).
account_debit_and_bank_slipPart debited from the account, the rest charged by bank slip.

status enumerator​

ValueDescription
openOpen fee.
pendingAwaiting payment.
paidPaid fee.
written_offWritten-off fee.

Export status enumerator​

ValueDescription
pendingExport registered, awaiting processing.
processingFile being generated.
doneFile ready for download until expires_at.
expiredFile removed after the 7-day period. Make a new request.

Related webhooks​

When the file is ready, the requester receives the invoice_export webhook.

Next step​

Query the fee export to get the download link.