API Reference

Import an invoice with file attached

post
https://app.pennylane.com/api/external/v2/customer_invoices/import

This endpoint allows you to import an invoice. Amounts are stored exactly as provided — Pennylane does not recalculate or round them.

ℹ️ Amount consistency: The amounts you send must be internally coherent:

  • currency_amount_before_tax + currency_tax must equal currency_amount.
  • The sum of invoice line currency_tax values must match the invoice-level currency_tax.
  • The sum of invoice line currency_amount values must match the invoice-level currency_amount.

Small rounding differences are tolerated. When convert_to_e_invoice is true, stricter requirements apply — see that field's description.

ℹ️

This endpoint requires the following scope: customer_invoices:all

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
int64
required

ID of a previously uploaded file attachment. The attachment must already have a file.
If the file is not available yet, the API returns 409; retry after a few seconds.

boolean
Defaults to false

This will set the invoice to Incomplete status

date
required

Invoice date (ISO 8601)

date
required

Invoice payment deadline (ISO 8601)

int64
required

Customer identifier

string

Invoice number. When convert_to_e_invoice is true, must be at most 35
characters and only contain alphanumeric characters and -+_/.

string
enum
Defaults to EUR
string
required
length ≥ 1
^(-?\d+(\.\d+)?)?$

Invoice currency amount before tax (total value before tax of the invoice in the currency of the invoice)

string
required
length ≥ 1
^(-?\d+(\.\d+)?)?$

Invoice currency amount (total value of the invoice in the currency of the invoice)

string
^(-?\d+(\.\d+)?)?$

Invoice amount in euros (total value of the invoice in euros). If the currency is euro, currency_amount and amount are identical.

string
required
length ≥ 1
^(-?\d+(\.\d+)?)?$

Invoice taxable amount (in invoice currency)

string
^(-?\d+(\.\d+)?)?$

Invoice taxable amount (in euros). If the currency is euro, currency_tax and tax are identical.

string | null

Custom label for the invoice used on accounting (ledger) entries. If not provided, Pennylane generates a label automatically.

transaction_reference
object

By adding this field you can automatically reconcile the newly imported invoice with a transaction. See documentation about automatic payment matching.

invoice_lines
array of objects
required
length ≥ 1
invoice_lines*
string
required
length ≥ 1
^(-?\d+(\.\d+)?)?$

Invoice line total amount in the currency of the invoice.

string
^(-?\d+(\.\d+)?)?$

Invoice line amount in euros. If the currency is euro, currency_amount and amount are identical.

string
required
length ≥ 1
^(-?\d+(\.\d+)?)?$

Invoice line taxable amount (in invoice currency)

string
^(-?\d+(\.\d+)?)?$

Invoice line taxable amount (in euros). If the currency is euro, currency_tax and tax are identical.

string

Line item label. Required when convert_to_e_invoice is true.

number
required

Line item quantity (number of items)

int64

The ledger account ID

string
enum

Resolves the line's ledger account to the company's goods or services account.

Unlike customer invoice create, import does not auto-fill fields from product_id, and product_id is not checked against substance.

When provided together with ledger_account_id, both must refer to the same account. If they do not match, the request returns 422.

Allowed:
string
required

The unit price excluding taxes. Can be set up to 6 decimals.

string
required

Line item unit (type of unit)

string
enum
required

Product VAT rate. A 20% VAT in France is FR_200.

string | null
deprecated

The description of the invoice line

⚠️

This attribute is deprecated and will be removed soon.

int64

The product ID

imputation_dates
object | null
ledger_entry_line
object
discount
object

Line-level discount. Only allowed when convert_to_e_invoice is true — sending this field without conversion enabled is an error. All amounts must be provided after discount — no recomputation is performed. Use relative for a percentage discount and absolute for a fixed amount discount.

boolean
Defaults to false

When set to true, Pennylane will asynchronously convert the imported invoice
into a Factur-X e-invoice (PDF/A-3) by embedding a structured XML into the
provided PDF. The invoice is returned immediately in the response; the
conversion happens in the background shortly after.
Requires file_attachment_id to reference a PDF file, all invoice lines to
have a label, and invoice_number to not exceed 35 characters and only
contain alphanumeric characters and -+_/.

Important: The company must have an invoice template with a footer
configured in Pennylane, including the three mandatory French legal notices
("Late payment penalties", "Fixed recovery cost for late payment", and
"Early payment discount"). Without this, the generated e-invoice will fail
French BR-FR compliance validation.

Factur-X amount compliance (BR-CO-14/BR-CO-15): The Factur-X XML standard
requires the sum of line-level currency_tax values to equal the invoice-level
currency_tax exactly, and currency_amount_before_tax + currency_tax to equal
currency_amount exactly. A difference of even a few cents will produce a
non-compliant XML. Ensure your amounts are fully consistent before sending.

discount
object

Invoice-level discount. Only allowed when convert_to_e_invoice is true — sending this field without conversion enabled is an error. All amounts must be provided after discount — no recomputation is performed. Use relative for a percentage discount and absolute for a fixed amount discount.

int64

ID of an existing customer invoice in Pennylane that this credit note credits.
The imported document must have negative amounts (a credit note).
The referenced invoice must exist in the same company, belong to the same
customer, be finalized (not a draft), not itself be a credit note, and have
enough remaining amount to absorb the credit note.

string

A unique external reference you can provide to track this customer invoice. If not provided, Pennylane will generate an identifier for you.

string | null

Buyer's purchase order reference (e-invoice field BT-13). Maximum 50 characters.

string | null

Seller's sales order reference (e-invoice field BT-14). Maximum 50 characters.

int64 | null
⚠️

This is a beta feature. Available only for selected companies during rollout.

The field is ignored when the feature is not enabled for the company.
If you plan to rely on it, please get in touch with us first.

Ledger account used for reconciliation by payment method.
When set, the receivable (e.g. 411) is transferred to this
account and the invoice outstanding balance becomes 0.

installments
array of objects
length ≥ 2

Optional list of installments for this invoice.
If not provided, a single installment matching the invoice total is created automatically.
The sum of all installments' amount values must equal the invoice total amount with tax.

ℹ️

This endpoint requires a company plan that has access to Installments, otherwise responds with 403.

⚠️

Warning: This feature is in alpha

The installments param will be ignored until further rollout and the request will proceed as if it was made without it
If you plan to rely on it, please get in touch with us first

installments
date
required

Installment payment deadline (ISO 8601)

string
required
^-?\d+(\.\d+)?$

Installment amount (in invoice currency)

payment_methods
array of strings, unique
date
required

Installment payment deadline (ISO 8601)

string
required
^-?\d+(\.\d+)?$

Installment amount (in invoice currency)

payment_methods
array of strings, unique
Responses

Updated 4 months ago

Language
Credentials
OAuth2
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 4 months ago