Articles on: Resources

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, invoice_linked, date_issue, 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

original_id

name

billing_email

country

billing_address.zip

zip_code

Products & Plans

Hyperline field

Fincome field

original_id

name

Subscriptions

Hyperline field

Fincome field

original_id

customer_id

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

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

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

Updated on: 01/06/2026

Was this article helpful?

Thank you!