# Pennylane integration mapping

### Connecting to Pennylane

[Follow this guide](/help-center/en/guide/sources/connect-my-pennylane-account.md) to establish the connection to the Pennylane API.

### Synchronized data

| **Entity**                    | **Key fields synchronized**                                                                                                                 |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Customers                     | id, name, email, country, postal\_code, client\_reference                                                                                   |
| Products (Products)           | id, name                                                                                                                                    |
| Prices (Prices)               | id, amount\_excluding\_tax, currency (linked\_to\_product)                                                                                  |
| Subscriptions (Subscriptions) | id, linked\_customer, status, start and end dates, monthly\_amount                                                                          |
| Invoices (Invoices)           | <p>id, status, date, number, customer<br>• Lines: linked\_product, amount\_excluding\_tax, VAT, currency, quantity, period, description</p> |
| Credit Notes (Credit Notes)   | Extracts of credit\_notes attached to an invoice                                                                                            |

***

### Detailed operation of the integration

* Structured mapping: all entities are mapped field by field from the Pennylane structure
* Subscription detection: based on billing patterns (invoice\_template.line\_items)
* Amounts excluding tax and taxes: analyzed line by line, with conversion to base currency
* Integrated credit notes: via invoice credit\_notes, with reversed amount
* Service periods: extracted automatically (period\_start, period\_end)

***

### To know

* Draft invoices (is\_draft): not synchronized
* Discounts: not imported currently (field forced to 0)
* Daily synchronization: every night automatically
* Data deletion in Pennylane: not propagated to Fincome
* Custom references: supported via the customers' reference field
* Incremental synchronization not supported: data must be extracted in full

***

### Integration overview

| Item                      | Detail                                                             |
| ------------------------- | ------------------------------------------------------------------ |
| Integration method        | OAuth 2.0 or Pennylane API key                                     |
| Supported entities        | Customers, Products, Prices, Subscriptions, Invoices, Credit Notes |
| Synchronization frequency | Daily (night)                                                      |
| Scope of initial import   | Data available via API                                             |
| Synchronization method    | REST API with pagination                                           |
| Pennylane data deletion   | Not supported                                                      |

***

### Data settings

| Behavior / Setting             | Operation in Fincome                                          |
| ------------------------------ | ------------------------------------------------------------- |
| Customer country / Postal code | Detection via several priority fields (country\_alpha2, etc.) |
| Subscriptions                  | From billing templates (template)                             |
| Amounts excluding tax / taxes  | Fields currency\_price\_before\_tax, currency\_tax            |
| Credit notes                   | Reversed lines, with structure identical to invoices          |
| Discounts                      | Not available (reported as 0)                                 |
| Currency conversion            | Based on currency and date                                    |
| Billing periods                | period\_start, period\_end extracted by Fincome               |

***

### Technical mapping (Pennylane → Fincome)

#### Customers

| Pennylane field                                                                      | Fincome field                 |
| ------------------------------------------------------------------------------------ | ----------------------------- |
| source\_id                                                                           | original\_id                  |
| name                                                                                 | name                          |
| email                                                                                | email                         |
| country\_alpha2, billing\_address.country\_alpha2, delivery\_address.country\_alpha2 | country                       |
| postal\_code, billing\_address.postal\_code, delivery\_address.postal\_code          | zip\_code                     |
| reference                                                                            | custom\_axis\_field.reference |

#### Products & Prices

| Pennylane field    | Fincome field                  |
| ------------------ | ------------------------------ |
| source\_id         | original\_id (product & price) |
| label              | name (product & price)         |
| price\_before\_tax | amount                         |
| currency           | currency\_code                 |

#### Subscriptions

| Pennylane field                                        | Fincome field                 |
| ------------------------------------------------------ | ----------------------------- |
| invoice\_template.line\_items\[].product\_id           | price\_id                     |
| invoice\_template.currency                             | currency\_code                |
| invoice\_template.line\_items\[].subscription\_set\_id | subscription\_set\_id         |
| start                                                  | subscription\_start\_date     |
| stopped\_at                                            | canceled\_at                  |
| finish                                                 | effective\_cancellation\_date |
| activated\_at                                          | deal\_closed\_date            |

#### Invoices & Lines

| Pennylane field     | Fincome field          |
| ------------------- | ---------------------- |
| id                  | original\_id (invoice) |
| date                | date                   |
| invoice\_number     | invoice\_number        |
| status              | status                 |
| customer.source\_id | customer\_id           |

#### Invoice lines

| Pennylane field              | Fincome field                           |
| ---------------------------- | --------------------------------------- |
| id                           | original\_id (line)                     |
| product\_id                  | price\_id                               |
| currency\_price\_before\_tax | amount\_excluding\_tax\_after\_discount |
| currency\_tax                | tax\_amount                             |
| label                        | description                             |
| quantity                     | quantity                                |
| currency                     | currency\_code                          |
| Periods                      | period\_start, period\_end              |

#### Credit notes

| Pennylane field                 | Fincome field                 |
| ------------------------------- | ----------------------------- |
| credit\_notes\[].id             | original\_id                  |
| currency\_price\_before\_tax    | amount (reversed)             |
| currency\_tax                   | tax\_amount (reversed)        |
| currency                        | currency\_code                |
| Discounted amount               | discount\_amount = 0 (forced) |
| Credit note attached to invoice | credit\_note\_id, invoice\_id |

***

### Next steps

* Check your KPIs in the MRR, Churn, and Cohorts views
* Add other billing sources (Stripe, Chargebee, etc.)
* Enrich your customer data (segmentation, company size...)
* Schedule a session with your Customer Success to go further


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://fincome.gitbook.io/help-center/en/resources/integration-mapping-and-api/pennylane-integration-mapping.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.