Hyperline integration guide
Welcome to the Hyperline integration guide with Fincome. This document guides you step by step to connect your Hyperline billing data to Fincome.
Prerequisites
Before starting, make sure that:
You are the administrator of your Hyperline account.
You are logged into the Hyperline platform (active session).
Your environment allows OAuth redirects (HTTPS required).
Introduction to the integration
The Hyperline integration enables automatic synchronization of the following items into Fincome:
Customers
Products and plans
Subscriptions
Invoices and credit notes
This data is then transformed to feed strategic metrics such as MRR, churn, cohorts, committed revenue, discount analysis, and much more.
Integration steps
1. Connecting to Hyperline from Fincome
Log in to your Fincome account.
Go to the Data tab.
Click Connect a new billing system:
Select Hyperline.
Click Connect Hyperline:
An OAuth window opens: sign in to your Hyperline account and authorize access to Fincome.
Once the connection is established, the initial synchronization starts automatically.
2. Data synchronized
Customers
ID, name, email, country, postal code
Products & Plans
ID, name, custom properties
The plan in Hyperline (configuration of multiple products at specific prices) is not represented in Fincome. A plan in Fincome represents a single product at a certain price and billing periodicity.
Subscriptions
ID, linked customer, status, start/end dates, monthly value, commitment end date
Invoices & Credit notes
Invoice: issue date, status.
Invoice lines: net amounts, discounts, taxes, currencies, billing periods
Credit note: related invoice, issue date, status
Credit note line: related invoice line, net amounts
Detailed operation of the integration
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 with field-by-field accuracy.
Trial detection: Fincome automatically identifies trial periods from trial_ends_at or, failing that, from contract_start.
Granular MRR: each subscription line is tracked individually to reflect changes (upgrade, downgrade...).
Cancellation handling: canceled or inactive subscriptions are properly processed, with 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 on the invoice date.
Smart synchronization: updates in Hyperline are detected and re-synchronized automatically. Any manual change in Fincome is given priority and preserved.
To know
Duration of the initial synchronization: several hours may be required depending on the data volume.
Daily synchronization: every night automatically.
Manual overwrite: any modification made in Fincome takes precedence over future synchronizations.
Hyperline rate limit: automatically managed by Fincome with retry after 30 seconds.
OAuth token expiration: automatic refresh by Fincome.
Integration overview
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 the 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
How it works in Fincome
Trial detection
Based on trial_ends_at or contract_start
MRR calculation
From the product line plan, adjusted according to currency and date
End of contractual commitment
Derived from contract_end
Cancellation handling
Based on detached_at or cancel_at
Subscription details
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
country
country
billing_address.zip
zip_code
Products & Plans
Hyperline field
Fincome field
id
original_id
name
name
id
plan.original_id
name
plan.name
id (product)
plan.product_id
Subscriptions
Hyperline field
Fincome field
id
original_id
customer_id
customer_id
status
status (interpreted)
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
calculated
monthly_value / monthly_value_main
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)
Need help?
Our support team is available via the in-app chat or by email: [email protected]
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
Last updated