How to integrate with Pennylane: Scopes agreed in advance and four weeks of changelog

Most accounting platforms let you register an application yourself, click through a consent screen and have working credentials within ten minutes. Pennylane does not. There is no self-service registration for integration partners, and the first step of the build is an email rather than a form.

Pennylane states it plainly in its OAuth walkthrough: “Before using OAuth, register your app with Pennylane by contacting our Partnerships team.” Only after that validation do you receive a client ID and secret.

The same requirement appears in Maesn’s Pennylane integration notes: it is “necessary to establish a direct relation with Pennylane and receive your client credentials from them”. What the connection then looks like object by object is on the Pennylane API page.

This is not a queue you can shorten, so it belongs in the project plan rather than in the sprint. It also changes what your sandbox story looks like, because sandbox access follows the same split.

A Maesn sandbox does exist for Pennylane, alongside the ones for DATEV, Fortnox and Twinfield, and it counts for more here than usual because Pennylane publishes no free trial account of any kind. The documented route to it is “please contact us” rather than a signup form, so it shortens the wait on Pennylane without removing the conversation.

The scope list is the part of the conversation that outlives it. Pennylane asks you to “supply them the details of your integration including the scopes required”, and what you name there is what your token will carry in production.

The grammar is deliberately coarse. A scope is either resource:readonly, which Pennylane defines as “Read-only access (GET endpoints only)”, or resource:all, which is “Full access (read + write + delete)”. There is no create-only and no update-only. You are choosing per resource, not per verb.

Maesn’s connection is configured against eleven of them. Eight are :all, two are read-only and one carries no suffix at all:

Line those eleven up against what the connection actually exposes and the shape of the integration becomes visible before you write anything. Two objects are supported today, nineteen more are readable on request and sixteen are not exposed here at all.

Your scope list was agreed in a conversation, which means your code has no record of what was actually granted on the other side. Pennylane answers that directly: GET /me returns the active scopes for your token, and it is the one endpoint that needs no scope of its own to answer.

Once the credentials exist the flow is a standard authorisation code grant against app.pennylane.com. The token exchange is unremarkable, and the number to read out of the response is expires_in.

Two durations, from the same page: “Access tokens expire after 24 hours” and “Refresh tokens are valid for 90 days”. A seven day credential lifetime circulates in secondary write-ups of this system and matches neither figure, nor anything else in Pennylane’s documentation.

Rotation itself is ordinary. What is worth reading closely is how immediate Pennylane makes it, because that decides whether your refreshes need to be serialised.

There is a second consequence that only shows up in operations. A refresh token survives 90 days of inactivity, so an integration that goes quiet keeps its credentials far longer than the 24 hour access token suggests. That becomes a problem in combination with the changelog window, which the sync section below works through.

Multi-entity products have one more decision here. Pennylane issues tokens in two contexts: a company token reaches a single company, while a firm token “can access resources across multiple client companies managed by the firm”.

The visible set “depends on who granted access and their internal permissions”. For a product selling to accounting practices that distinction is the difference between one connection and hundreds.

Creating a business document in v2 means one call per object, and Pennylane ties that directly back to the scope list you agreed at the start: “each object has to be created separately, through a dedicated endpoint. This also is enforced by the granularity of scopes.”

Pennylane gives the example that matters for billing. A customer cannot be created inline with an invoice: it is “mandatory to first create the customer” and then pass its ID. File attachments work the same way: upload to /file_attachments, take the ID, then reference it as file_attachment_id on the import.

So the number of round trips per business document is a function of how many objects it touches, and each of those objects needs its own scope. That is the same sentence as the scope section, arrived at from the write side.

Two things v2 will not do for you at all, per Pennylane’s supported use cases: create a downpayment invoice or a delivery note. If either is in your product flow, find out now rather than in the second sprint.

Pennylane’s error handling is genuinely good, with a consistent JSON schema, a useful details object and a documented retry matrix. The expensive cases are the ones that never reach it, because they answer with a success code.

The first is pagination. Version two moved to cursors, and the cursor carries less than it looks like it does:

The second is the changelog checkpoint, and Pennylane flags it as an explicit warning rather than a footnote: “Do not update your start_date checkpoint until you have fully paginated through all pages (has_more: false). If you stop mid-pagination, resume from your last next_cursor.” Advance the checkpoint after page one of four and pages two to four are gone, with nothing anywhere reporting a gap.

The third is duplication on write. Pennylane is direct about it: “If the same request is sent twice, you may create duplicates”, and idempotency is “not enforced on creation endpoints” such as /customer_invoices and /ledger_entries. There is exactly one exception, and it is oddly specific.

What is left is the ordinary part, and it is well built. A 403 means the token lacks the scope, with the missing name in the message. A 422 means a business rule failed, with the offending field in details.

Pennylane also publishes which codes deserve a retry, 429 and 500 and 503, and which never do, 400 and 401 and 403 and 404 and 422. Mapping those onto one behaviour across systems is what unified error handling is for.

Pennylane does send events. It sends three, they are in beta, and Pennylane’s own advice is not to depend on them yet: “The webhooks feature is in Beta. We recommend falling back on changelog endpoints during this phase.”

The three are customer_invoice.e_invoicing_status_updated, dms_file.created and supplier_invoice.e_invoicing_received. All three are about e-invoicing status or a document arriving, which is a very French set of concerns and a reasonable place to start given the country’s invoicing regime.

Note what is not in that list. Neither of the two objects this connection supports today, customers and suppliers, announces its own changes. For those you poll, which is what the changelog endpoints are for and what unified webhooks has to work around when a system offers no event for an object.

The changelog endpoints cover seven resources, including both live objects: customer_invoices, supplier_invoices, customers, suppliers, products, ledger_entry_lines and transactions. Each change gives you an ID and an operation, so the pattern is a delta read followed by a batch fetch.

Then the limit that decides your architecture: “Changes are retained for 4 weeks”, and you “cannot request changes older than 4 weeks”. That number matters next to the 90 day refresh token because the two expire at different speeds. Credentials survive 90 days of silence. An incremental catch-up stops being possible after 28. So an integration can pause for five weeks, reconnect without an error anywhere, and still be missing a fortnight of changes it can no longer ask for.

Rate limits set the pace of that recovery, and the documented figure is a window rather than a per-second rate. Pennylane allows “up to 25 requests every 5 seconds”, applied “at the token level”, on sandbox as well as production, and with “all endpoints ... affected”. Per token matters: the budget scales with connected companies rather than being shared across your whole app.

What that costs on a recovery run follows from those two figures alone. Reading 10.000 changes at the default page size of 20 takes 500 changelog calls plus 500 batch reads, so 1.000 requests, which is 40 windows and about 200 seconds.

The same recovery at the documented maximum of 1.000 per page is 20 requests and fits inside a single window. The default is the expensive choice, and it is the one you get by not passing limit.

One helpful detail while you tune that: the ratelimit-limit, ratelimit-remaining and ratelimit-reset headers are returned on successful responses too, not only on a 429. You can pace against your remaining budget rather than discovering the ceiling by hitting it.

A unified interface takes over most of what the sections above describe. It does not take over the partner relationship, and that split is what decides a Pennylane project’s timeline, because the half that stays with you has the longest lead time in it.

What the connection takes off your desk:

• Token lifecycle, including the rotation trap. The 24 hour expiry, the single-use refresh token and the serialisation that stops two workers destroying each other’s credentials.
• One shape for customers and suppliers. The two supported objects arrive in the same normalised form they take for every other connected system, so the mapping is written once.
• Pacing against the token budget. Requests are queued and retried against the 25 per 5 seconds ceiling rather than against a 429 you handle yourself.
• Cursor handling with the filter attached. The failure mode from the reading section stops being something each integration has to remember.
• A sandbox for a system with no free trial. Pennylane offers no trial account, and a Maesn environment is available on request.

What stays with you, and the first item is a commercial task rather than a technical one:

• The relationship with Pennylane. The client ID and secret are issued to you, by their partnerships team, against your scope list. Nobody can hold that conversation on your behalf, and it is the long lead time in the plan.
• Deciding the scope list. Which objects your product needs is a product question. It is also close to irreversible, since widening the list later means going back to the same team.
• Your own re-sync policy past 28 days. The changelog window is Pennylane’s, and what your product does when it has been exceeded is yours.
• Deduplication on write. With no idempotency key outside supplier invoice imports, not sending the same create twice remains your responsibility.