Chargebee integration mapping
Connecting to Chargebee
Follow this guide to establish the connection with the Chargebee API.
Synchronized data
Entity
Synchronized key fields
Customers
id, name, email, country, postal_code
Products
id, name
Prices (Prices)
id, name, duration, period, type, amount, currency, item_type
Subscriptions
id, customer_id, status, trial_dates, subscription_start, cancellation, commitment_end
Invoices
id, status, customer, date
Invoice Lines
linked_price, description, amounts_excl_tax, discounts (temp/perm), taxes, quantity, period, currency
Credit Notes
id, status, original_invoice
Credit Note Lines
same structure as the invoice (with amounts inverted)
Detailed operation of the integration
- Field-to-field mapping: each Chargebee entity is finely translated according to the mapping provided by the API
- Multi-line subscriptions: Fincome analyzes subscription.subscription_items individually
- Cancellations interpreted: cancelled_at, cancel_schedule_created_at are taken into account
- Reconstructed MRR: from the prices associated with each active item_price, adjusted according to the period
- Differentiated discounts: temporary and permanent handled separately, per line
- Currency conversion: based on currency_code + created_at (or date) depending on the object type
Note
- Initial synchronization: depends on history, may take a few hours
- Automatic update: every night + update via webhook
- Custom fields: available via metadata in customer and subscription objects
- Reporting of deleted lines: via deleted_at
- Only non-voided credit notes: voided credit notes are not imported
- Manual deletion in Chargebee: not propagated
Integration overview
Item
Detail
Integration method
OAuth 2.0 (direct connection via App Store)
Supported entities
Customers, Products, Prices, Subscriptions, Invoices, Credit Notes
Sync frequency
Daily + real-time Webhooks
Scope of initial import
All data available via API
Synchronization method
Chargebee REST API with pagination
Deletion of Chargebee data
Managed via deleted or IdPathOrResourceDeleted
Data settings
Setting or field
Operation in Fincome
subscription_items
Each line is tracked individually
Trial detection
Fields trial_start and trial_end
Subscription dates
started_at or start_date
End of contractual commitment
Reconstructed via dedicated method (GetContractualCommitmentEndDate)
Line-by-line discounts
temporary_discount_amount vs discount_amount
Currency conversion
Via currency_code + created_at or invoice.date
Deleted subscriptions
deleted_at is set if the subscription disappeared
Technical mapping (Chargebee → Fincome)
Customers
Chargebee field
Fincome field
original_id
customer.relationship.root_id
root_parent_id
customer.billing_address.country
country
customer.billing_address.zip
zip_code
customer.metadata
custom_axis_field
Products & Prices
Chargebee field
Fincome field
original_id (product)
name (product)
item_family_id
chargebee_item_family (axis)
item_price.id
original_id (price)
item_price.name
name (price)
item_price.period_unit
period_unit
item_price.period
period_length
item_price.amount
amount
item_price.currency_code
currency_code
item_price.item_type
chargebee_item_type (axis)
Subscriptions
Chargebee field
Fincome field
original_id
subscription.status
status
subscription.customer_id
customer_id
subscription.subscription_items[].item_price_id
price_id
subscription.started_at / start_date
subscription_start_date
subscription.trial_start
trial_start
subscription.trial_end
trial_end
subscription.cancel_schedule_created_at / cancelled_at
canceled_at
subscription.cancelled_at
effective_cancellation_date
subscription.created_at
deal_closed_date
calculated
monthly_value, monthly_value_main
subscription.metadata
custom_axis_field
Invoices & Lines
Chargebee field
Fincome field
original_id
invoice.date
date
invoice.status
status
invoice.customer_id
customer_id
invoice.line_items[].id
original_id (line)
item_price_id
price_id
subscription_id
subscription_id
quantity
quantity
amount_after_discount
amount_excluding_tax_after_discount
tax_amount
tax_amount
line_item_discounts (perm)
discount_amount
line_item_discounts (temp)
temporary_discount_amount
description
description
date_from, date_to
period_start, period_end
invoice.currency_code
currency_code
Credit Notes
Chargebee field
Fincome field
credit_note.id
original_id
credit_note.line_items
credit note lines
credit_note.status != voided
import filter
amount
amount_excluding_tax_after_discount
discount_amount
discount_amount
temporary_discount_amount
temporary_discount_amount
description, date_from, date_to
description, period_start, period_end
Next steps
- View 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
Thank you!