Netsuite integration mapping

Connection to NetSuite

Follow these steps to connect Fincome to NetSuite:

1. Make sure your NetSuite account is enabled for REST Web Services and has the appropriate role/permissions.
2. Obtain the following credentials from your NetSuite account or your integration record:

• Account ID (replace _ with - in the URLs)
• Client ID

Note: The connector currently implements a Machine-to-Machine flow (client_credentials / JWT). Interactive OAuth flows are present in the code but not yet implemented. OAuth will be the main method for NetSuite WebServices.

Synchronized data

NetSuite object

Synchronized key fields

Customers

id, entityId (name), email

Invoices (transaction + lines + currency)

invoice_id, invoice_number, customer_id, date, status, invoice_line_item_id, description, netamount, foreignamount, currency_code, period_start, period_end

Currency

symbol → currency_code

Detailed integration behavior

• SuiteQL extraction The connector composes SuiteQL queries combining the objects transaction, transactionLine and currency. The selected fields are hard-coded for now, but could become configurable in the future.
• Incremental extraction

The NetSuite integration supports incremental extraction via the field last_modified_date.

• Authentication & token refresh

• Access tokens expire after one hour and are refreshed automatically.
• Line type classification

• The NetSuite connector determines if a line is subscription or one_off based on the custom field custcol_iw_item_revenue_category and the validity of the period dates.
• Currency handling

• The connector retrieves currency.symbol as currency_code.
• If netamount and foreignamount both exist, the latter can be used to calculate original currency or base currency amounts as needed.

Things to know

• Custom fields used The connector uses NetSuite custom fields (e.g. custcol_iw_rr_start_date, custcol_iw_rr_end_date, custcol_iw_item_revenue_category). If your NetSuite account uses other IDs, update fields_per_object, where_conditions and the mapping logic accordingly.
• Date formats The connector expects DD/MM/YYYY. Adjust the OperationMap Date if NetSuite returns a different format.
• Pagination and offsets SuiteQL supports limit and offset. Large historical synchronizations can take time; the connector updates the cursor and resumes automatically.
• Scope & permissions The integration requires the scope rest_webservices and an account/role with read access to transaction, transactionLine, currency and customer data.

Integration overview

Item

Detail

Integration method

JWT client-assertion → OAuth2 token (Machine-to-Machine)

Supported objects

customer, transaction (invoice), transactionLine, currency

Sync frequency

Incremental via cursor + on-demand token refresh

Initial import

Full history via SuiteQL with offset pagination

Synchronization method

SuiteQL queries via NetSuite REST query/v1/suiteql endpoint

Deletions

Not propagated (soft-deletes must be handled separately)

Data settings & behaviors

Parameter

Behavior

Date format

%d/%m/%Y via the OperationMap Date

Invoice status mapping

A → open, B → paid, D → pending, others ignored

Invoice line classification

custcol_iw_item_revenue_category + period dates

Amounts inversion

netamount currently inverted in IliAmount

Filter

Invoices with custcol_iw_item_revenue_category IS NOT NULL and netamount IS NOT NULL

Technical mapping (NetSuite → Fincome)

Customers

NetSuite

Fincome

id

original_id

entityId

name

email

email

Invoices & Lines

NetSuite

Fincome

t.id

original_id (invoice)

t.number

invoice_number

t.entity

customer_id

t.tranDate

date

t.status

status (via InvoiceStatus)

tl.id

original_id (invoice line)

tl.item

product / SKU

tl.netamount

amount_excluding_tax_after_discount (currently inverted)

tl.foreignamount

optional foreign amount

tl.memo

description

tl.custcol_iw_rr_start_date

period_start

tl.custcol_iw_rr_end_date

period_end

cur.symbol

currency_code

Credit Notes

NetSuite

Fincome

transaction with recordtype = credit note

original_id (credit note)

linked invoice

invoice_id

line id

original_id (credit note line)

netamount

amount (negative)

foreignamount

optional foreign amount

memo

description

start/end dates

period_start / period_end

currency.symbol

currency_code

Updated on: 01/06/2026