Hyperline integration mapping
Connecting to Hyperline
Follow this guide 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 | |
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
Updated on: 03/07/2026
Thank you!