PEpennylane
Customer Invoices

Update a customer invoice

Changed on

Update a customer invoice

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

put/api/external/v2/customer_invoices/{id}

Request

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

Path parameters

idinteger required

The unique identifier of the customer invoice

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

OR

Example request

{
  "date": "2023-08-30",
  "deadline": "2023-08-30",
  "customer_id": 42,
  "customer_invoice_template_id": 42,
  "pdf_invoice_free_text": "Additional free field",
  "pdf_invoice_subject": "Invoice title",
  "pdf_description": "Invoice description",
  "special_mention": "Additional details",
  "discount": {
    "value": "25"
  },
  "invoice_lines": {
    "create": [
      {
        "product_id": 42,
        "label": "Demo label",
        "ledger_account_id": 1255,
        "raw_currency_unit_price": "33.333334",
        "unit": "piece",
        "vat_rate": "FR_200",
        "quantity": 12,
        "section_rank": 1,
        "discount": {
          "value": "25"
        },
        "custom_fields": [
          {
            "name": "color"
          }
        ],
        "performance_period": {
          "start_date": "2023-07-01",
          "end_date": "2023-07-31"
        }
      }
    ],
    "update": [
      {
        "id": 42,
        "label": "Demo label",
        "quantity": 12,
        "ledger_account_id": 1255,
        "raw_currency_unit_price": "33.333334",
        "unit": "piece",
        "vat_rate": "FR_200",
        "product_id": 42,
        "discount": {
          "value": "25"
        },
        "section_rank": 1,
        "custom_fields": [
          {
            "name": "color"
          }
        ],
        "performance_period": {
          "start_date": "2023-07-01",
          "end_date": "2023-07-31"
        }
      }
    ],
    "delete": [
      {
        "id": 42
      }
    ]
  },
  "label": "Custom accounting label",
  "external_reference": "FR123",
  "installments": {
    "create": [
      {
        "deadline": "2023-08-30",
        "amount": "20.00"
      }
    ],
    "update": [
      {
        "id": 42,
        "deadline": "2023-08-30",
        "amount": "20.00"
      }
    ],
    "delete": [
      {
        "id": 42
      }
    ]
  }
}

Response

A 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 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 DE_intracom_exempt_BU0233 enum value to the 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_goods 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_intracom_sales_services 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_100 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_purchases_210 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_isp_sales 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 ES_suplido enum value to the request property /////

    • info

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

    • info

      added the new es_ES 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 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