API V2 vs V1

V1

The first version of the API is destined to be deprecated at some point in 2026. It will be progressively replaced by our new API offer : The Company API & The Firm API.

❗️

Depreciation strategy

The V1 will not be depreciated in the first semester of 2025. However, it will not contain any new feature. Starting 2025, all new features will be implemented in the v2 directly.

Firm API

Firm API is a new API dedicated to firms or softwares that cater to firms, accessible via your firm token and via firm OAuth., and gives access to your companies portfolio. It contains the following features :

• Retrieve accounting reports (Analytical ledger, trial balance, FEC, etc.)
• Retrieve companies

V2 - Company API

The v2 is now called the 'Company API'. It allows SMEs to handle their finances along with accounting through different features.

Company API is accessible via your developer token and via company OAuth. It contains the following features :

• Sales management (create customer invoices, drafts, customers, products, etc.)
• Purchases management (create supplier invoices, suppliers, etc.)
• Accounting management (create accounting entries, ledger accounts, etc.)
• Analytical tags management (categorize sales & purchases)
• Retrieve accounting reports (Analytical ledger, trial balance, FEC, etc.)

What changes between v1 and v2 ?

API v1 IDs vs. API v2 IDs

The new API V2 relies exclusively on internal IDs to expose and retrieve any resources (product, customer, etc.).
For instance, you cannot retrieve a product via its source_id but only via its internal id.
To help you migrate from V1 to V2, all the resources in the V1 response payloads now include an additional v2_id attribute so you can map the old IDs to the new IDs.

More granular scopes 🔐

In the v2, we’ve introduced more granular scopes to ensure your integration accesses the adequate data from a Pennylane Company.

Each scope now comes with its readonly counterpart, which is the preferred scope if your app only needs to read information.

Example

customer_invoices in the v1 is now broken down into multiple scopes :

• customer_invoices
  • read & write
• products
  • read & write
• customers
  • read & write
• drafts
  • read & write
• credit_notes
  • read & write
• file_attachements
  • read & write

New pagination

To bring more performance, we've changed the pagination system. Read here our dedicated guide.

Creating ressources separately

In the v1, it was possible to create multiple types of objects in a single call, which was problematic for performance & debugging issues, and led to many errors. In the v2, each object has to be created separately, through a dedicated endpoint. This also is enforced by the granularity of scopes. We make sure that ressources can be created only if you or the third party you've given access to has a scope authorized.

Example

• In the v1, it was possible to create a customer while creating a customer_invoice.
• In the v2, it is now mandatory to first create the customer through the customer creation endpoint, and then pass on its ID in the customer creation endpoint.

Renaming attributes & ressources

Some attributes & ressources have been renamed ⬇️

• plan_item -> ledger_account
• customer_validation_needed -> import_as_incomplete

Managing file attachments

In the API V1, to attach a file when importing a customer invoice, you had to provide either the file field with the base64 content of the file or file_url with the URL to download it. In the V2, this file is a dedicated resource called a file_attachment. So, to import a customer invoice with a file, you first need to upload a file attachment, get the ID, and use that ID in the import customer invoice endpoint with the file_attachment_id field.

Exposing nested collections in the response body in V2

In the API V2, whenever we have to expose a nested collection in a response, such as invoice_lines of a customer_invoice, we will provide a link towards the collection instead of an array/list of invoice_line ids.

Standardized response body in V2

We have standardized the response body in V2, meaning that a data model (such as customer_invoice, for example) will always have the same response body attributes exposed, regardless of the endpoint (show, list).

Changelogs

We've added changelog endpoints on most common ressources (customer_invoices, supplier_invoices, suppliers, customers, suppliers, etc.) to allow you to list the events and changes that happened over a ressource. Read here our full guide.

More filters

To be more performant while querying endpoints, we've added new filters in the V2. Look at our guide to setting up filters here.