Sign in

v1

latestOpenAPI 3.0.12026-07-141671231.8 MB
Customer Invoices

Import an invoice with file attached

This endpoint allows you to import an invoice.

ℹ️ To ensure consistency, we will apply validations on amounts in accordance with our rounding policy. We allow a difference up to 1 cent per invoice_line between the total amounts and the sum of invoice lines. For further details, please refer to our article on rounding policy.

ℹ️ This endpoint requires the following scope: customer_invoices:all

post/api/external/v2/customer_invoices/import

Request body

file_attachment_idinteger required

File attachment id

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

external_referencestring

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

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"
      },
      "ledger_entry_line": {
        "label": "Demo label"
      },
      "discount": {
        "value": "10"
      }
    }
  ],
  "discount": {
    "value": "10"
  },
  "external_reference": "FR123"
}

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' | '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)

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

filenamestring nullable required

Name of the file attached to the invoice

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)

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",
  "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"
  },
  "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"
  },
  "quote": {
    "id": 42
  },
  "external_reference": "FR123",
  "archived_at": "2023-08-30T10:08:08.146343Z",
  "created_at": "2023-08-30T10:08:08.146343Z",
  "updated_at": "2023-08-30T10:08:08.146343Z"
}