> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.fincome.co/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Hyperline integration mapping

![](https://storage.crisp.chat/users/helpdesk/website/-/6/2/0/e/620ea71851239000/hyperlinecologo_1q9oxgu.jpeg =100x100)
# Connecting to Hyperline

[Follow this guide](https://help.fincome.co/en/article/connect-my-hyperline-account-6sgwfn/) to establish the connection with the Hyperline API.
---
# Synchronized data

| **Hyperline entity** | **Key synchronized fields** |
| ---- |
| Customers | id, name, email, country, zip_code |
| Products | id, name, custom_properties⚠️ The plan in Hyperline (a configuration of several products at specific prices) is not reproduced in Fincome. A plan in Fincome represents a single product at a certain price and billing periodicity. |
| Subscriptions | id, customer_id, status, start_date, end_date, monthly_value, commitment_end_date |
| Invoices | id, issue_date, status |
| Invoice Line Items | net_amounts, discounts, taxes, currencies, period_start, period_end, revenue_type |
| Credit Notes | id, linked_invoice, issue_date, status |
| Credit Note Lines | linked_invoice_line, net_amounts |
---
# How the integration works in detail

The integration with Hyperline is designed to be smooth, reliable, and transparent. Here is how it works:

* Smart object mapping: each Hyperline entity (customer, product, subscription, invoice) is translated into Fincome precisely, field by field.
* Trial period detection: Fincome automatically identifies trial periods from trial_ends_at or, failing that, contract_start.
* Cancellation handling: canceled or inactive subscriptions are correctly processed, with the cancellation and effective 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 the exchange rates in effect at the billing date.
* Smart synchronization: updates in Hyperline are detected and re-synced automatically. Any manual change in Fincome takes priority and is preserved.
* Invoice line type (one-off or subscription): according to Hyperline-specific rules
        * when a product is attached to a subscription with a 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".
---
# Good to know

* Duration of the first synchronization: several hours may be needed 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 a retry after 30 seconds.
* OAuth token expiration: automatically refreshed by Fincome.
---
# Integration overview

| **Element** | **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 the initial import | Historical data since 01/01/2007 |
| Synchronization method | Cursor pagination with take and skip |
| Data deletion from Hyperline | Not supported – deletions in Hyperline are not propagated |
---
# Data settings

| **Behavior / Setting** | **How it works in Fincome** |
| ---- |
| Trial detection | Based on trial_ends_at or contract_start |
| MRR calculation | From the invoice line type, adjusted according to the currency and the date |
| Contractual commitment end | From contract_end |
| Cancellation handling | Based on detached_at or cancel_at |
| Subscription detail | Each subscription line is tracked separately |
| Discount handling | Deduced from coupons, temporary or permanent |
| Currency conversion | Applied via currency_code and billing date |
| Re-synchronization | 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 Cohort 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