Hyperline integration mapping
Connecting to Hyperline
Follow this guide 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, invoicelinked, dateissue, 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
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
Last updated