Import a Customer Invoice

How to Import Customer Invoices via API

This tutorial will guide you through the process of importing customer invoices into Pennylane using our API endpoints.

Prerequisites

Before importing invoices, you need:

• OAuth token with customer_invoices:all and file_attachments:all scopes
• Customer ID (existing customer)
• Product IDs (if using products, optional)
• Ledger account IDs (for precise accounting mapping, optional)

Step 1: Upload the Invoice PDF

First, upload your PDF invoice using the file attachments endpoint:

POST https://app.pennylane.com/api/external/v2/file_attachments

This will return an id that will be used as file_attachment_id in the next step.

Step 2: Import the Invoice

Use the following endpoint to import the invoice in Pennylane:

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

Required Information:

1. File Attachment ID: Use the ID obtained from Step 1
2. Customer Information: You'll need the customer_id
   • Find existing customers: GET /customers
   • Create new company customer: POST /company_customers
   • Create new individual customer: POST /individual_customers
3. Dates: Provide date and deadline of the invoice
4. Amounts: Provide the following amounts
   1. currency_amount_before_tax : Invoice currency amount before tax ("montant HT de la facture" in French)
   2. currency_amount : Invoice currency amount ("montant TTC de la facture" in French)
   3. currency_tax : Invoice taxable amount ("montant de la TVA de la facture" in French)

Invoice Line Details:

Each invoice line requires:

• currency_amount: Total amount for the line
• currency_tax: Total VAT amount for the line
• quantity: Number of units sold
• raw_currency_unit_price: Unit price excluding VAT ("prix unitaire hors taxe" in French)
• unit: Unit type (e.g., "hour", "kilogram", "piece")
• vat_rate: VAT rate code (e.g., "FR_200" for 20%)

Ledger Accounts: It is advised to provide on each invoice line a ledger_account_id in order for Pennylane to generate accounting entries properly mapped to accounts

• Find existing accounts: GET /ledger_accounts?filter=\[{"field": "number", "operator": "start_with", "value": "YOUR_ACCOUNT_NUMBER"}\]
• Create new account: POST /ledger_accounts\

Example request body :

JSON

{
  "file_attachment_id": your_file_id,
  "customer_id": customer_id,
  "date": "YYYY-MM-DD",
  "deadline": "YYYY-MM-DD",
  "currency_amount_before_tax": "100.00",
  "currency_amount": "120.00",
  "currency_tax": "20.00",
  "invoice_lines": [
    {
      "ledger_account_id": account_id,
      "currency_amount": "120.00",
      "currency_tax": "20.00",
      "quantity": 2,
      "raw_currency_unit_price": "50.00",
      "unit": "piece",
      "vat_rate": "FR_200"
    }
  ]
}

Optional - Step 3: Categorize the Invoice

After creating the invoice, you can categorize it:

1. Get or create a category:

   • Find existing categories: GET /categories
   • Create new category: POST /categories

2. Apply the category:
   PUT /customer_invoices/{invoice_id}/categories

Include the category weight in the request body:

JSON

[
  {
    "id": category_id,
    "weight": "0.5"
  },
  {
    "id": category_id,
    "weight": "0.5"
  }
]

Note: The weight represents the percentage allocation to this category (e.g., 1 for 100%, 0.5 for 50%).

That's it! Your sales invoice has been imported, created, and categorized in Pennylane.