Invoices
No OAuth-enabled endpoints in this section. Turn off the OAuth filter in the sidebar to see all of its endpoints.
Invoices API
Export Billable Items for a Billing Period
Exports the billable items of all ready invoices of the given type, year and month in one stream, ordered by invoice. The type is cpo-usage, msp-usage or msp-usage-delayed-sessions; the export has the same format, columns, amount precision and completeness guards as Export Billable Items for a single invoice. The 200 response lists one schema per invoice type. Every row carries invoiceId and invoiceIdentifier, so the rows of one invoice can be grouped.
By default the export also covers invoices of child providers the caller has invoice read access to. Set includeChildProviderInvoices to false to only export invoices of the provider itself.
The export is available as NDJSON (default), CSV or XLSX; select the format with the Accept header. The endpoint responds 409 when the data behind one of the invoices is not complete yet; retry later. It responds 503 when the export cannot be produced right now. It never returns a partial file.
User sessionAPI credentialinvoices:readQuery parameters4
Header parameters1
Selects the format of the 200 response by standard content negotiation, q-values included. Without the header, or with /, the response is NDJSON.
application/x-ndjsontext/csvapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet200The billable items of the billing period NDJSON · CSV · XLSX
Accept: application/x-ndjsonDefaultOne JSON record per line. The last line is an end frame, {"type": "end", "totalCount": n}, whose totalCount is the number of record lines. A response without the end frame was cut off before the export completed; discard it and retry.
ID of the billed account.
Name of the billed account.
Net amount of the item as used in invoice calculations. Not rounded to cents.
Gross amount of the item (amount plus VAT), as used in the invoice calculations. Not rounded to cents.
Amount in currency the percentage was applied to. Null otherwise.
ID of the billable item. Unique per row.
ID of the billing plan the fee comes from. Null when the item has none.
English name of the billing plan the fee comes from. Null when the item has none.
How the amount was calculated: fixed (quantity times rate) or percentage (percentage of baseAmount). Null when the item carries no rate.
EVSE ID of the charge point, for charger fees and session-derived fees. Null otherwise.
OCPP identity of the charge point, for charger fees and session-derived fees. Null otherwise.
Serial number of the charge point, for charger fees and session-derived fees. Null otherwise.
ISO 4217 alpha code for the currency of the invoice; applies to amount, amountWithVat, rate and baseAmount.
ID of the charge point (EVSE controller), for charger fees and session-derived fees. Null otherwise.
Stable fee type. Known values, more may be added:
charging_station_socket_subscription_fee: recurring fee per connector of a charging station.charging_station_installation_fee: one-off fee per charging station.account_tier_subscription_fee: recurring fee of the account tier.cpo_kwh_usage_fee: platform fee per kWh charged on the CPO's chargers.cpo_per_session_fee: fixed fee per session.cpo_roaming_surcharge_fee: surcharge on a roaming session.payment_authorization_fee: fee per payment authorisation of a Tap to Pay or Scan to Pay session.payment_capture_fee: fee per payment capture of a Tap to Pay or Scan to Pay session.manual_invoicing_fee: fee for an invoice that is not collected automatically.other: an item that matches no known type.
ID of the invoice the row belongs to.
Invoice number as printed on the invoice PDF.
Human-readable name of the fee as shown on the invoice.
ID of the location of the charge point or the session. Null when none resolves.
Name of the location of the charge point or the session. Null when none resolves.
ID of the payment, for payment fees. Null otherwise.
Payment flow of the session, for payment fees: tap-to-pay or scan-to-pay. Null otherwise.
Percentage applied to baseAmount for percentage calculations. Null otherwise.
Billed quantity in the unit of the fee type, such as kWh for usage fees or connectors for socket fees.
Unit price in currency for fixed calculations. Null otherwise.
End of the session, ISO 8601 in UTC. Null on rows not derived from a session.
Session ID given by the charge point or roaming partner, as shown in the sessions export. Null when absent.
ID of the charging session, as shown in the sessions export. Null on rows not derived from a session.
Energy of the session in kWh, rounded to three decimals. Null on rows not derived from a session.
Start of the session, ISO 8601 in UTC. Null on rows not derived from a session.
ID of the owner of the location the row belongs to. Null when the location has no owner.
Name of the owner of the location the row belongs to. Null when the location has no owner.
VAT percentage applied to the item, for example 21.
ID of the VAT rule applied. Null when no rule was recorded.
400Invalid Request application/json
errorobject
401Unauthorized application/json
errorobject
403Forbidden: missing a required permission, or no access to this resource application/json
errorobject
404Not Found application/json
errorobject
406No supported export format matches the Accept header application/json
errorobject
409The data behind one of the invoices is not complete yet; retry later application/json
errorobject
429Too many requests: the rate limit was exceeded application/json
errorobject
500Internal server error application/json
errorobject
503The export cannot be produced right now; retry later application/json
errorobject
Search Invoices
Searches invoices for the current provider, with filters, sorting and pagination.
By default the results also include invoices of child providers the caller has invoice read access to. Set includeChildProviderInvoices to false to only return invoices of the provider itself.
User sessionAPI credentialinvoices:readRequest bodyapplication/json
true500sortobjectdefault {"field":"createdAt","order":"desc"}
{"field":"createdAt","order":"desc"}createdAtidentifiermonthtypeyearascdesc200OK application/json
dataPublicInvoiceResource[]
ID of the account the invoice was issued to.
Billing period the invoice covers.
ISO 4217 currency code of the invoice.
errorPublicInvoiceErrorDetails of the error that occurred while generating the invoice. Only present on invoices with errors.
Details of the error that occurred while generating the invoice. Only present on invoices with errors.
breakdownobjectUnderlying errors grouped by error code.
Underlying errors grouped by error code.
Total number of underlying errors.
Highest impact among the underlying errors:
- fatal: the invoice data cannot be trusted
- incomplete: some billable items were skipped, so the invoice is incomplete, but what is there is accurate
- not-billable: the invoice is fine, but the customer cannot be billed because details are missing
fatalincompletenot-billableHuman-readable summary of the error.
Total invoice amount, including VAT. For reimbursement invoices this is the reimbursed amount.
Whether an error occurred while generating the invoice.
Unique identifier of the invoice.
Human-readable invoice number. Absent when the invoice has not been processed yet.
Invoice date in YYYY-MM-DD format. For invoices generated without an explicit invoice date, this is derived from the invoice period or creation date.
Whether the invoice has been fully generated and is ready.
Month the invoice applies to (1-12).
Total invoice amount, excluding VAT. For reimbursement invoices this is the reimbursed amount.
Payment method used for the invoice. Absent on reimbursement invoices, and when the account has no payment method configured.
Payment term of the invoice, in days. Absent on reimbursement invoices, and when the account has no payment term configured.
ID of the provider that issued the invoice.
Type of the invoice:
- msp-usage: charges an account for the charge sessions and subscriptions of its drivers
- msp-usage-delayed-sessions: msp-usage variant covering sessions received after the original billing run
- cpo-usage: charges an account for its CPO subscriptions and usage fees
- cpo-credit: reimburses an account for the charge sessions delivered on its charge points
- cpo-credit-delayed-sessions: cpo-credit variant covering sessions received after the original billing run
cpo-creditcpo-credit-delayed-sessionscpo-usagemsp-usagemsp-usage-delayed-sessionsID of the user the invoice belongs to. Only present on user-based invoices.
vatBreakdownPublicInvoiceVatBreakdownValue[]REQUIREDAmounts on the invoice aggregated per applied VAT rule.
Amounts on the invoice aggregated per applied VAT rule.
Whether the amount for this VAT rule is negative. Note that a negative amount may be rounded to 0, so check this flag instead.
Whether VAT is not applicable.
Whether reverse charge applies.
Total amount for this VAT rule, excluding VAT.
VAT amount for this VAT rule.
VAT percentage applied by the rule.
ID of the VAT rule that was applied.
Year the invoice applies to.
metaobject
400Invalid Request application/json
errorobject
401Unauthorized application/json
errorobject
403Forbidden: missing a required permission, or no access to this resource application/json
errorobject
404Not Found application/json
errorobject
500Internal server error application/json
errorobject
Get Invoice
Returns a single invoice by ID.
User sessionAPI credentialPath parameters1
200OK application/json
dataPublicInvoiceResource
ID of the account the invoice was issued to.
Billing period the invoice covers.
ISO 4217 currency code of the invoice.
errorPublicInvoiceErrorDetails of the error that occurred while generating the invoice. Only present on invoices with errors.
Details of the error that occurred while generating the invoice. Only present on invoices with errors.
breakdownobjectUnderlying errors grouped by error code.
Underlying errors grouped by error code.
Total number of underlying errors.
Highest impact among the underlying errors:
- fatal: the invoice data cannot be trusted
- incomplete: some billable items were skipped, so the invoice is incomplete, but what is there is accurate
- not-billable: the invoice is fine, but the customer cannot be billed because details are missing
fatalincompletenot-billableHuman-readable summary of the error.
Total invoice amount, including VAT. For reimbursement invoices this is the reimbursed amount.
Whether an error occurred while generating the invoice.
Unique identifier of the invoice.
Human-readable invoice number. Absent when the invoice has not been processed yet.
Invoice date in YYYY-MM-DD format. For invoices generated without an explicit invoice date, this is derived from the invoice period or creation date.
Whether the invoice has been fully generated and is ready.
Month the invoice applies to (1-12).
Total invoice amount, excluding VAT. For reimbursement invoices this is the reimbursed amount.
Payment method used for the invoice. Absent on reimbursement invoices, and when the account has no payment method configured.
Payment term of the invoice, in days. Absent on reimbursement invoices, and when the account has no payment term configured.
ID of the provider that issued the invoice.
Type of the invoice:
- msp-usage: charges an account for the charge sessions and subscriptions of its drivers
- msp-usage-delayed-sessions: msp-usage variant covering sessions received after the original billing run
- cpo-usage: charges an account for its CPO subscriptions and usage fees
- cpo-credit: reimburses an account for the charge sessions delivered on its charge points
- cpo-credit-delayed-sessions: cpo-credit variant covering sessions received after the original billing run
cpo-creditcpo-credit-delayed-sessionscpo-usagemsp-usagemsp-usage-delayed-sessionsID of the user the invoice belongs to. Only present on user-based invoices.
vatBreakdownPublicInvoiceVatBreakdownValue[]REQUIREDAmounts on the invoice aggregated per applied VAT rule.
Amounts on the invoice aggregated per applied VAT rule.
Whether the amount for this VAT rule is negative. Note that a negative amount may be rounded to 0, so check this flag instead.
Whether VAT is not applicable.
Whether reverse charge applies.
Total amount for this VAT rule, excluding VAT.
VAT amount for this VAT rule.
VAT percentage applied by the rule.
ID of the VAT rule that was applied.
Year the invoice applies to.
metaobject
400Invalid Request application/json
errorobject
401Unauthorized application/json
errorobject
404Not Found application/json
errorobject
500Internal server error application/json
errorobject
Export Billable Items
Exports the billable items of a single invoice. Billable items are the individual lines that make up an invoice, such as charge sessions, recurring fees and one-off costs.
For cpo-usage, msp-usage and msp-usage-delayed-sessions invoices the export is available as NDJSON (default), CSV or XLSX; select the format with the Accept header. Every row carries a human-readable label, a stable fee type, the billed account name and the calculation fields (quantity, rate, calculation type). A cpo-usage row adds charger and session context, the payment method for payment fees, and the percentage and base amount of percentage fees. An MSP row adds the token and card identity, the session context and, for session usage, the CPO price, its currency and the exchange rate. The columns depend on the invoice type. The 200 response lists one schema per invoice type; the schema describes every column and the known fee types.
The token and card identity columns of an MSP row (tokenVisualNumber, tokenContractId, nameOnCard, cardRequestedAt) show the current token and card data, not the data at the time of the session.
amount and amountWithVat carry each item as it was invoiced, not rounded to cents. The invoice PDF rounds its totals to two decimals with banker's rounding (half to even), so a plain sum of the rows can differ from the PDF total by rounding.
The endpoint responds 409 when the data behind the invoice is not complete yet; retry later. It responds 503 when the export cannot be produced right now. It never returns a partial file.
Reimbursement invoices are exported as CSV (default) or XLSX, with columns depending on the invoice type.
User sessionAPI credentialPath parameters1
Header parameters1
Selects the format of the 200 response by standard content negotiation, q-values included. Without the header, or with /, the response is NDJSON.
application/x-ndjsontext/csvapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet200The billable items of the invoice NDJSON · CSV · XLSX
Accept: application/x-ndjsonDefaultOne JSON record per line. The last line is an end frame, {"type": "end", "totalCount": n}, whose totalCount is the number of record lines. A response without the end frame was cut off before the export completed; discard it and retry.
ID of the billed account.
Name of the billed account.
Net amount of the item as used in invoice calculations. Not rounded to cents.
Gross amount of the item (amount plus VAT), as used in the invoice calculations. Not rounded to cents.
Amount in currency the percentage was applied to. Null otherwise.
ID of the billable item. Unique per row.
ID of the billing plan the fee comes from. Null when the item has none.
English name of the billing plan the fee comes from. Null when the item has none.
How the amount was calculated: fixed (quantity times rate) or percentage (percentage of baseAmount). Null when the item carries no rate.
EVSE ID of the charge point, for charger fees and session-derived fees. Null otherwise.
OCPP identity of the charge point, for charger fees and session-derived fees. Null otherwise.
Serial number of the charge point, for charger fees and session-derived fees. Null otherwise.
ISO 4217 alpha code for the currency of the invoice; applies to amount, amountWithVat, rate and baseAmount.
ID of the charge point (EVSE controller), for charger fees and session-derived fees. Null otherwise.
Stable fee type. Known values, more may be added:
charging_station_socket_subscription_fee: recurring fee per connector of a charging station.charging_station_installation_fee: one-off fee per charging station.account_tier_subscription_fee: recurring fee of the account tier.cpo_kwh_usage_fee: platform fee per kWh charged on the CPO's chargers.cpo_per_session_fee: fixed fee per session.cpo_roaming_surcharge_fee: surcharge on a roaming session.payment_authorization_fee: fee per payment authorisation of a Tap to Pay or Scan to Pay session.payment_capture_fee: fee per payment capture of a Tap to Pay or Scan to Pay session.manual_invoicing_fee: fee for an invoice that is not collected automatically.other: an item that matches no known type.
ID of the invoice the row belongs to.
Invoice number as printed on the invoice PDF.
Human-readable name of the fee as shown on the invoice.
ID of the location of the charge point or the session. Null when none resolves.
Name of the location of the charge point or the session. Null when none resolves.
ID of the payment, for payment fees. Null otherwise.
Payment flow of the session, for payment fees: tap-to-pay or scan-to-pay. Null otherwise.
Percentage applied to baseAmount for percentage calculations. Null otherwise.
Billed quantity in the unit of the fee type, such as kWh for usage fees or connectors for socket fees.
Unit price in currency for fixed calculations. Null otherwise.
End of the session, ISO 8601 in UTC. Null on rows not derived from a session.
Session ID given by the charge point or roaming partner, as shown in the sessions export. Null when absent.
ID of the charging session, as shown in the sessions export. Null on rows not derived from a session.
Energy of the session in kWh, rounded to three decimals. Null on rows not derived from a session.
Start of the session, ISO 8601 in UTC. Null on rows not derived from a session.
ID of the owner of the location the row belongs to. Null when the location has no owner.
Name of the owner of the location the row belongs to. Null when the location has no owner.
VAT percentage applied to the item, for example 21.
ID of the VAT rule applied. Null when no rule was recorded.
400Invalid Request application/json
errorobject
401Unauthorized application/json
errorobject
404Not Found application/json
errorobject
406No supported export format matches the Accept header application/json
errorobject
409The data behind the invoice is not complete yet; retry later application/json
errorobject
500Internal server error application/json
errorobject
503The export cannot be produced right now; retry later application/json
errorobject
Get Invoice PDF
Returns a temporary download URL for the PDF document of an invoice. The URL is valid for one hour; treat it as a secret, since anyone holding it can download the document.
Returns 404 when the invoice PDF has not been rendered yet.
User sessionAPI credential