Sign in

v1

latestOpenAPI 3.0.12026-07-141671231.8 MB
Supplier Invoices

Import a supplier invoice with a file attached

This endpoint allows you to import a supplier invoice with a file attached.

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

post/api/external/v2/supplier_invoices/import

Request body

file_attachment_idinteger required

The ID of the supplier invoice file attachment to import

import_as_incompleteboolean

This will mark the invoice as incomplete.

supplier_idinteger required

The ID of the supplier to import the invoice for

datestring date required

The date of the invoice (ISO 8601)

deadlinestring date required

Invoice payment deadline (ISO 8601)

invoice_numberstring

The invoice number

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.

external_referencestring

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

Example request

{
  "file_attachment_id": 123,
  "supplier_id": 456,
  "date": "2021-01-30",
  "deadline": "2021-01-30",
  "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": [
    {
      "label": "Demo label",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor",
      "currency_amount": "120.00",
      "amount": "120.00",
      "currency_tax": "20.00",
      "tax": "20.00",
      "ledger_account_id": 1255,
      "vat_rate": "FR_200",
      "imputation_dates": {
        "start_date": "2020-06-30",
        "end_date": "2021-06-30"
      },
      "ledger_entry_line": {
        "label": "Demo label"
      }
    }
  ],
  "external_reference": "FR123"
}

Response

The imported supplier invoice

idinteger required

The ID of the supplier invoice

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.

reconciledboolean required

Whether the invoice has been reconciled or not

accounting_status'draft' | 'archived' | 'entry' | 'validation_needed' | 'complete' required

The accounting state of the invoice.

  • draft: The invoice is not yet sent to the accountant.
  • archived: The invoice has been archived.
  • entry: The invoice is incomplete. Some information is missing on the invoice and needs to be completed by SME.
  • validation_needed: The invoice is sent to the accountant and needs validation.
  • complete: The invoice has been validated by the accountant.
filenamestring nullable required

Name of the file attached to the invoice

public_file_urlstring nullable required

Public URL of the invoice file. The URL will expire after 30 minutes.

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

payment_status'to_be_processed' | 'to_be_paid' | 'partially_paid' | 'payment_error' | 'payment_scheduled' | 'payment_in_progress' | 'payment_emitted' | 'payment_found' | 'paid_offline' | 'fully_paid' required
paidboolean required

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

external_referencestring required

The unique external reference that was assigned during creation either by you or Pennylane

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": 123,
  "label": "Demo 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": "2023-09-30",
  "currency_tax": "34.0",
  "tax": "34.0",
  "filename": "my_file.pdf",
  "public_file_url": "https://app.pennylane.com/public/invoice/pdf?encrypted_id=bzjoVJe...3D%3D",
  "remaining_amount_with_tax": "20.0",
  "remaining_amount_without_tax": "16.0",
  "ledger_entry": {
    "id": 42003
  },
  "supplier": {
    "id": 456,
    "url": "https://app.pennylane.com/api/external/v2/suppliers/42"
  },
  "invoice_lines": {
    "url": "https://app.pennylane.com/api/external/v2/supplier_invoices/42/invoice_lines"
  },
  "categories": {
    "url": "https://app.pennylane.com/api/external/v2/supplier_invoices/42/categories"
  },
  "transaction_reference": {
    "banking_provider": "bank",
    "provider_field_name": "label",
    "provider_field_value": "invoice_number"
  },
  "payments": {
    "url": "https://app.pennylane.com/api/external/v2/supplier_invoices/42/payments"
  },
  "matched_transactions": {
    "url": "https://app.pennylane.com/api/external/v2/supplier_invoices/42/matched_transactions"
  },
  "external_reference": "FR123",
  "e_invoicing": {
    "source_file_url": "https://app.pennylane.com/rails/active_storage/blobs/redirect/abc123/invoice.xml"
  },
  "archived_at": "2023-08-30T10:08:08.146343Z",
  "created_at": "2023-08-30T10:08:08.146343Z",
  "updated_at": "2023-08-30T10:08:08.146343Z"
}