# Hyperline integration mapping
### Connecting to Hyperline
[Follow this guide](/en/guide/sources/connect-my-hyperline-account.md) to establish the connection with the Hyperline API.
### Synchronized data
| **Hyperline entity** | **Synchronized key fields** |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Customers (Customers) | id, name, email, country, postal\_code |
| Products (Products) | id, name, custom\_properties
⚠️ The plan in Hyperline (configuration of multiple products at specific prices) is not reproduced in Fincome. A plan in Fincome represents a single product at a certain price and a billing periodicity.
|
| Subscriptions (Subscriptions) | id, customer\_id, status, start\_date, end\_date, monthly\_value, commitment\_end\_date |
| Invoices (Invoices) | id, issue\_date, status |
| Invoice Line Items (Invoice Line Items) | net\_amounts, discounts, taxes, currencies, period\_start, period\_end, revenue\_type |
| Credit Notes (Credit Notes) | id, invoice*linked, date*issue, status |
| Credit Note Lines (Credit Note Lines) | linked\_invoice\_line, net\_amounts |
***
### Detailed operation of the integration
The integration with Hyperline is designed to be seamless, reliable and transparent. Here is how it works:
* Smart object mapping: each Hyperline entity (customer, product, subscription, invoice) is translated into Fincome accurately field by field.
* Detection of trial periods: Fincome automatically identifies trial periods from trial\_ends\_at or, if absent, from contract\_start.
* Cancellation handling: canceled or inactive subscriptions are properly processed, with cancel and actual end dates.
* Discount analysis: discounts from Hyperline coupons are interpreted and broken down (temporary vs permanent).
* Currency conversion: all data is converted into the reference currency using exchange rates in effect on the invoice date.
* Intelligent synchronization: updates in Hyperline are detected and resynchronized automatically. Any manual modification in Fincome takes precedence and is preserved.
* Invoice line type (one-off or subscription): according to rules specific to Hyperline
* when a product is attached to a subscription with recurrence, the line is identified as "recurring";
* when a product is not attached to a subscription, or to a subscription without recurrence, the line is identified as "one-off";
* when a product is attached to a recurring subscription and corresponds to usage, the line is identified as "variable".
***
### Note
* Duration of the initial synchronization: several hours may be required depending on the data volume.
* Daily synchronization: every night automatically.
* Manual override: any change made in Fincome takes precedence over future synchronizations.
* Hyperline rate limit: handled automatically by Fincome with retry after 30 seconds.
* OAuth token expiration: automatic refresh by Fincome.
***
### Overview of the integration
| **Item** | **Detail** |
| ------------------------------- | ---------------------------------------------------------- |
| Integration method | OAuth 2.0 (direct connection from Fincome) |
| Supported entities | Customers, Products, Subscriptions, Invoices, Credit Notes |
| Synchronization frequency | Daily (at night) |
| Scope of initial import | Historical data since 01/01/2007 |
| Synchronization method | Cursor pagination with take and skip |
| Deletion of data from Hyperline | Not supported – deletions in Hyperline are not propagated |
***
### Data settings
| **Behavior / Setting** | **Operation in Fincome** |
| ----------------------------- | ------------------------------------------------------------------- |
| Detection of trials | Based on trial\_ends\_at or contract\_start |
| MRR calculation | From the invoice line type, adjusted according to currency and date |
| End of contractual commitment | From contract\_end |
| Cancellation handling | Based on detached\_at or cancel\_at |
| Subscription detail | Each subscription line is tracked separately |
| Discount processing | Derived from coupons, temporary or permanent |
| Currency conversion | Applied via currency\_code and invoice date |
| Resynchronization | Automatic; manual changes are never overwritten |
***
### Technical mapping (Hyperline → Fincome)
#### Customers
| **Hyperline field** | **Fincome field** |
| -------------------- | ----------------- |
| id | original\_id |
| name | name |
| billing\_email | email |
| country | country |
| billing\_address.zip | zip\_code |
#### Products & Plans
| **Hyperline field** | **Fincome field** |
| ------------------- | ----------------- |
| id | original\_id |
| name | name |
#### Subscriptions
| **Hyperline field** | **Fincome field** |
| --------------------------------- | ---------------------------------- |
| id | original\_id |
| customer\_id | customer\_id |
| status | status |
| contract\_start | trial\_start |
| trial\_ends\_at / contract\_start | trial\_end |
| detached\_at / cancel\_at | canceled\_at |
| attached\_at | deal\_closed\_date |
| contract\_start / attached\_at | subscription\_start\_date |
| contract\_end | contractual\_commitment\_end\_date |
| id (plan) | plan\_id |
#### Invoices & Lines
| **Hyperline field** | **Fincome field** |
| ---------------------- | --------------------------------------- |
| id | original\_id (invoice) |
| emitted\_at | date |
| billing status | status |
| invoice number | invoice\_number |
| line\_items.id | original\_id (line) |
| units\_count | quantity |
| amount\_excluding\_tax | amount\_excluding\_tax\_after\_discount |
| tax\_amount | tax\_amount |
| period\_start / end | period\_start / period\_end |
| coupons | discount\_amount(s) |
| revenue\_type | type (sub or one-off) |
***
### 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://help.fincome.co/en/resources/integration-mapping-and-api/hyperline-integration-mapping.md?ask=
```
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.