Hyperline integration mapping
Connecting to Hyperline
Follow this guide to establish the connection with the Hyperline API.
Synchronized data
Hyperline entity
Key fields synchronized
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, issued_date, status
Invoice Line Items (Invoice Line Items)
net_amounts, discounts, taxes, currencies, period_start, period_end
Credit Notes (Credit Notes)
id, invoicelinked, dateissue, status
Credit Note Lines (Credit Note Lines)
related_invoice_line, net_amounts
Detailed operation of the integration
The integration with Hyperline is designed to be seamless, reliable, and transparent. Here’s how it works:
Smart object mapping: each Hyperline entity (customer, product, subscription, invoice) is translated into Fincome field by field with precision.
Detection of trial periods: Fincome automatically identifies trial periods from trial_ends_at or, if absent, from contract_start.
Handling cancellations: canceled or inactive subscriptions are properly processed, with cancellation and effective end dates.
Analysis of discounts: 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.
Smart synchronization: updates in Hyperline are detected and re-synchronized automatically. Any manual modification in Fincome is prioritized and preserved.
Note
Duration of the first 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: managed automatically 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 (nightly)
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
Operation 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 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
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)
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