V1 to V2 Migration Guide

❗️

Depreciation strategy

The V1 will be completely depreciated by end of 2025. The V2 is now the official stable version.

Recognize the version you're using

💡To know on which version you are, have a look at the URL your code is using :

• If it's V1, the path should contain /v1
• if it's V2, the path should contain /v2

If you don't have access to the URL, look at your token generated in the connectivity page :

• If it has the following scopes, then it's V2 ⬇️
  • Écritures comptables
  • Balance générale
  • Exercices fiscaux
  • Export Grand Livre Analytique
  • Export Fichier des Écritures Comptables
  • Modèles de factures
  • Transactions
  • Comptes bancaires
  • Fichiers DMS
  • Catégories
  • Clients
  • Produits
  • Factures fournisseurs
  • Fournisseurs
  • Factures client
  • Fichiers
  • Mandats clients
  • Devis
  • Documents commerciaux
  • Abonnements de facturation
• if it has the following scopes, then it's v1 ⬇️
  • Analytique et reporting
  • Gestion des ventes
  • Gestion des fournisseurs

If you're using an OAuth App, here are the v1 scopes and the v2 scopes.

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
• file_attachements
  • read & write

💡 Add the new V2 scopes to your OAuth app and re-authenticate it to be able to use V2 endpoints !

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
• Estimates -> Quotes

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.

Floats are handled as strings

In the V2, to avoid errors when it comes to float values, it is now mandatory to pass them on as strings.

In the V1 :

In the V2 :