PEpennylane
Customer Invoices

Import an invoice with file attached

Changed on

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

post/api/external/v2/customer_invoices/import

Request

  • Base URL
    https://app.pennylane.com
  • URL
    https://app.pennylane.com/api/external/v2/customer_invoices/import
  • Auth
    OAuth 2
    Authorization code: https://app.pennylane.com/oauth/authorize
    Token URL: https://app.pennylane.com/oauth/oauth/token scopes: customer_invoices:all

Headers

X-Company-Idstring
Example:12345

Numeric ID of the company to act on. Required when authenticating with a firm token. Ignored when the token is already bound to a company.

Request body

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

import_as_incompleteboolean

This will set the invoice to Incomplete status

datestring date required

Invoice date (ISO 8601)

deadlinestring date required

Invoice payment deadline (ISO 8601)

customer_idinteger required

Customer identifier

invoice_numberstring

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

currency'EUR' | 'USD' | 'GBP' | 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BYR' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'FJD' | 'FKP' | 'GEL' | 'GGP' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'IMP' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JEP' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LTL' | 'LVL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SLE' | 'SOS' | 'SRD' | 'STD' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'UYU' | 'UZS' | 'VEF' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XDR' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMK' | 'ZMW' | 'ZWL'
currency_amount_before_taxstring required

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

currency_amountstring required

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

amountstring

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

currency_taxstring required

Invoice taxable amount (in invoice currency)

taxstring

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

labelstring nullable

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

convert_to_e_invoiceboolean

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 -+_/.

The attached PDF must not already embed a Factur-X (or ZUGFeRD) XML. If it does, the request can fail with an error asking you to use the customer e-invoice import endpoint (/customer_invoices/e_invoices/imports) instead. Use convert_to_e_invoice only for plain PDFs that Pennylane should convert.

Important: The three mandatory French legal notices ("Late payment penalties", "Fixed recovery cost for late payment", and "Early payment discount") are required. Either provide them in legal_notices, or configure them in the footer of the default invoice template of your Pennylane account. Without either, the request returns a 422 error.

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.

credited_invoice_idinteger

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.

external_referencestring

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

purchase_order_referencestring nullable

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

contract_referencestring nullable

Contract reference (e-invoice field BT-12). Maximum 50 characters.

electronic_billing_addressstring nullable

The electronic billing address of the customer used for the e-invoicing routing of this invoice. Use a value returned by the GET /api/external/v2/customers/{id}/electronic_billing_addresses endpoint. Only allowed when convert_to_e_invoice is true. When it is not sent, null, or an empty string, the electronic billing address of the customer is used.

Example request

{
  "file_attachment_id": 42,
  "date": "2023-08-30",
  "deadline": "2023-08-30",
  "customer_id": 42,
  "invoice_number": "F20230001",
  "currency_amount_before_tax": "100.00",
  "currency_amount": "120.00",
  "amount": "120.00",
  "currency_tax": "20.00",
  "tax": "20.00",
  "label": "Custom accounting label",
  "transaction_reference": {
    "banking_provider": "bank",
    "provider_field_name": "label",
    "provider_field_value": "invoice_number"
  },
  "invoice_lines": [
    {
      "currency_amount": "120.00",
      "amount": "120.00",
      "currency_tax": "20.00",
      "tax": "20.00",
      "label": "Demo label",
      "quantity": 12,
      "ledger_account_id": 1255,
      "raw_currency_unit_price": "33.333334",
      "unit": "piece",
      "vat_rate": "FR_200",
      "product_id": 42,
      "imputation_dates": {
        "start_date": "2020-06-30",
        "end_date": "2021-06-30"
      },
      "performance_period": {
        "start_date": "2023-07-01",
        "end_date": "2023-07-31"
      },
      "ledger_entry_line": {
        "label": "Demo label"
      },
      "discount": {
        "value": "10"
      }
    }
  ],
  "discount": {
    "value": "10"
  },
  "legal_notices": {
    "late_payment_penalties": "In case of late payment, a penalty of 3 times the legal interest rate will be applied.",
    "fixed_recovery_cost": "A fixed compensation of 40 EUR for recovery costs will be charged.",
    "discount_terms": "No discount for early payment."
  },
  "credited_invoice_id": 42,
  "external_reference": "FR123",
  "purchase_order_reference": "PO-2026-001",
  "contract_reference": "CT-2026-001",
  "electronic_billing_address": "123456789_00012"
}

Response

The imported customer invoice

idinteger required

Invoice identifier

labelstring nullable required
invoice_numberstring required
currency'EUR' | 'USD' | 'GBP' | 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BYR' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'FJD' | 'FKP' | 'GEL' | 'GGP' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'IMP' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JEP' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LTL' | 'LVL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SLE' | 'SOS' | 'SRD' | 'STD' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'UYU' | 'UZS' | 'VEF' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XDR' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMK' | 'ZMW' | 'ZWL' required
amountstring required

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

currency_amountstring required

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

currency_amount_before_taxstring required

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

exchange_ratestring required

Invoice exchange rate (used to convert the invoice to euros. If the invoice currency is euro it will be 1.0)

datestring date nullable required

Invoice issue date (ISO 8601)

deadlinestring date nullable required

Invoice payment deadline (ISO 8601)

performance_datestring date nullable required

End date of the performance period of the first invoice line that has one (ISO 8601). Used for German VAT accounting (Leistungsdatum). Null if the company does not use German accounting, or if no invoice line has a performance period.

currency_taxstring required

Invoice taxable amount (in invoice currency)

taxstring required

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

language'fr_FR' | 'en_GB' | 'de_DE' | 'es_ES' required

The local default is based on the thirdparty (customer / supplier ) billing_language . In case the customer is not present, we will default to the company locale.

paidboolean required

Invoice paid status (set to True if the invoice is paid)

status'archived' | 'incomplete' | 'cancelled' | 'paid' | 'partially_paid' | 'partially_cancelled' | 'upcoming' | 'late' | 'draft' | 'credit_note' | 'proforma' | 'shipping_order' | 'purchasing_order' | 'estimate_pending' | 'estimate_accepted' | 'estimate_invoiced' | 'estimate_denied' required
public_file_urlstring nullable required

Public URL of the invoice file. The URL will expire after 30 minutes. May be null if the PDF has not been generated yet (for example right after creation or finalization); fetch the invoice again to get the URL once it is available.

filenamestring nullable required

Name of the file attached to the invoice. May be null immediately after creation if the PDF has not been generated yet; fetch the invoice again to get the filename once it is available.

remaining_amount_with_taxstring nullable required

The remaining amount with VAT to pay for the invoice to be considered paid

remaining_amount_without_taxstring nullable required

The remaining amount without VAT to pay for the invoice to be considered paid

draftboolean required

Indicates if the invoice is in draft (has not been finalized)

special_mentionstring nullable required

Additional details

pdf_invoice_free_textstring required
pdf_invoice_subjectstring required
pdf_descriptionstring nullable required
external_referencestring required

The unique external reference that was assigned during creation either by you or Pennylane. (Same attribute as external_id in the API v1)

purchase_order_referencestring nullable required

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

contract_referencestring nullable required

Contract reference (e-invoice field BT-12). Maximum 50 characters.

sales_order_referencestring nullable required

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

factur_xboolean required

Whether the attached invoice file is a Factur-X document (a PDF/A-3 with an embedded structured XML).

schematron_validation_status'pending' | 'valid' | 'invalid' nullable required

Result of Schematron structural validation for Factur-X invoices. Only relevant when factur_x is true, null otherwise.

archived_atstring date-time nullable required

The time the invoice has been archived

created_atstring date-time required

The time the invoice has been created

updated_atstring date-time required

The last time the invoice has been updated

Example response

{
  "id": 42,
  "label": "Invoice label",
  "invoice_number": "F20230001",
  "amount": "230.32",
  "currency_amount": "230.32",
  "currency_amount_before_tax": "196.32",
  "exchange_rate": "1.0",
  "date": "2023-08-30",
  "deadline": "2020-09-02",
  "performance_date": "2023-07-31",
  "currency_tax": "34.0",
  "tax": "34.0",
  "discount": {
    "value": "25"
  },
  "ledger_entry": {
    "id": 42002
  },
  "public_file_url": "https://app.pennylane.com/public/invoice/pdf?encrypted_id=bzjoVJe...3D%3D",
  "filename": "my_file.pdf",
  "remaining_amount_with_tax": "20.0",
  "remaining_amount_without_tax": "16.0",
  "special_mention": "Additional details",
  "customer": {
    "id": 42,
    "url": "https://app.pennylane.com/api/external/v2/customers/42"
  },
  "payment_method_ledger_account": {
    "id": 1255,
    "url": "https://app.pennylane.com/api/external/v2/ledger_accounts/1255"
  },
  "invoice_line_sections": {
    "url": "https://app.pennylane.com/api/external/v2/customer_invoices/42/invoice_line_sections"
  },
  "invoice_lines": {
    "url": "https://app.pennylane.com/api/external/v2/customer_invoices/42/invoice_lines"
  },
  "custom_header_fields": {
    "url": "https://app.pennylane.com/api/external/v2/customer_invoices/42/custom_header_fields"
  },
  "categories": {
    "url": "https://app.pennylane.com/api/external/v2/customer_invoices/42/categories"
  },
  "pdf_invoice_free_text": "Thanks for paying this invoice",
  "pdf_invoice_subject": "Invoice subject",
  "pdf_description": "Invoice description",
  "credited_invoice": {
    "id": 40,
    "url": "https://app.pennylane.com/api/external/v2/customer_invoices/40"
  },
  "transaction_reference": {
    "banking_provider": "bank",
    "provider_field_name": "label",
    "provider_field_value": "invoice_number"
  },
  "payments": {
    "url": "https://app.pennylane.com/api/external/v2/customer_invoices/42/payments"
  },
  "matched_transactions": {
    "url": "https://app.pennylane.com/api/external/v2/customer_invoices/42/matched_transactions"
  },
  "appendices": {
    "url": "https://app.pennylane.com/api/external/v2/customer_invoices/42/appendices"
  },
  "installments": {
    "url": "https://app.pennylane.com/api/external/v2/customer_invoices/42/installments"
  },
  "quote": {
    "id": 42
  },
  "external_reference": "FR123",
  "purchase_order_reference": "PO-2026-001",
  "contract_reference": "CT-2026-001",
  "sales_order_reference": "SO-2026-001",
  "archived_at": "2023-08-30T10:08:08.146343Z",
  "created_at": "2023-08-30T10:08:08.146343Z",
  "updated_at": "2023-08-30T10:08:08.146343Z"
}

Changes

  • 871f863307e5Revision changes
    • warning

      added the new VES enum value to the response property for the response status

    • warning

      added the new es_ES enum value to the response property for the response status

    • info

      added the new optional header request parameter X-Company-Id

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new DE_intracom_exempt_BU0233 enum value to the request property //

    • info

      added the new ES_intracom_sales_goods enum value to the request property //

    • info

      added the new ES_intracom_sales_services enum value to the request property //

    • info

      added the new ES_isp_purchases_100 enum value to the request property //

    • info

      added the new ES_isp_purchases_210 enum value to the request property //

    • info

      added the new ES_isp_sales enum value to the request property //

    • info

      added the new ES_suplido enum value to the request property //

    • info

      added the new VES enum value to the request property

    • info

      added the new helloasso enum value to the request property /

    • info

      added the new order_id enum value to the request property /

    • info

      added the non-success response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property / to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status