NetSuite integration behaviour

Learn about the behaviour of the NetSuite integration for each of the data types it syncs.

Overview

The NetSuite integration syncs the following kinds of data:

  • Customers
  • Contacts
  • Opt-in and opt-out status
  • Items
  • Orders

For each of these kinds of data, there are certain behaviours that you should be aware of. These are listed in the relevant section below.

Before you start

Things you need to know:

Be aware

It is important to understand the behaviour and limitations of the integration prior to setting it up in order to avoid unexpected results.

Address data

  • The default billing address is exposed through the following fields for mapping purposes for prospect, lead, customer and contact records in NetSuite:
    • addr1
    • addr2
    • addr3
    • city
    • country
    • state
    • zip

Be aware

If you are syncing records bidirectionally and want to sync address data, you must map all the address fields, any address fields left unmapped will lose their values!

Duplicate email handling

NetSuite permits multiple contacts and customers to use the same email address, although it isn’t recommended it is very easy to do. This also applies to leads and prospects as they are just stages of a customer, which potentially results in multiple NetSuite records trying to map to a single Dotdigital contact, this is because email addresses are considered unique identifiers in Dotdigital.

mceclip0.png

The NetSuite integration ensures only a single NetSuite record is mapped to a single Dotdigital contact at any one time. This single mapping is important to prevent data corruption due to cross linking of multiple NetSuite records to a single Dotdigital contact when syncing bi-directionally.

The integration will allow the remapping of a Dotdigital contact to a later sales stage NetSuite record if the following is true:

  • The email addresses match
  • The names match (if enabled in your integrations multiple match handling settings)
  • They both are people or companies
  • It is a later sales stage

The sales stage order of importance is as follows:
mceclip1.png

The reason it is this order is so that you can continue to engage throughout the sales cycle and sync a customer's order history.

Customer data

  • Only customers records with an email address in NetSuite are synced.
  • Customers should be deduplicated by email; duplicate customers are not synced.
  • We cannot sync contact deletions from Dotdigital to NetSuite.
  • All email addresses are made lowercase.
  • You may opt to sync people, companies or both customer record types.
  • If opting to sync company records from NetSuite then the isPerson NetSuite field must be mapped to a Dotdigital Yes/No custom data field to indicate if the record is a company or person, and the companyname field must be mapped to Dotdigital text custom data field.
  • The status of a customer can be updated if the entitystatus field is mapped to a text field in Dotdigital that holds the customer status id.
  • When syncing back to NetSuite we will update a customer’s entitystatus with the default status for the customer stage if:
    • The customers current stage differs for the address book’s associated stage
    • We need to create a new customer record in NetSuite
  • Email addresses are validated prior to synchronisation. Invalid email addresses cannot be processed.
  • We cannot update a record’s email address if it conflicts with an existing customer, because the NetSuite API prevents duplicate records.
  • If a NetSuite customer has their email address removed then any Dotdigital contact associated with this email address is deleted.

Contacts

  • Only contacts that have an email address are synced.
  • Only contacts that are people entities in NetSuite and who have an email address are synced.
  • Contacts should be deduplicated by email; duplicate contacts are not synced.
  • We cannot sync contact deletions from Dotdigital to NetSuite.
  • Calculated fields cannot be synced, only stored fields can be synced
  • All email addresses are made lowercase.
  • It’s not possible to update a contact’s address in NetSuite from Dotdigital due to NetSuite API limitations.
  • The default billing address is exposed through the following fields for mapping purposes (read only):
    • addr1
    • addr2
    • addr3
    • city
    • country
    • state
    • zip
  • Email addresses are validated prior to synchronisation. Invalid email addresses cannot be processed.
  • We cannot update a record’s email address if it conflicts with an existing contact because the NetSuite API prevents duplicate records.
  • If a NetSuite contact has their email address removed then any Dotdigital contact associated with this email address is deleted.

Opt in/out status

Opt-in status is only synced if enabled, for only those entities you are syncing, and in the specified sync direction(s). For instance, to sync opt-in status for customers bi-directionally you must have opt-in status syncing enabled and set to bi-directional, and have enabled syncing customers either to Dotdigital or bi-directionally.

When an opt out status is synced to Dotdigital from NetSuite the Dotdigital contact is suppressed to prevent any marketing from being sent to it. It it subsequently opted back in to marketing and is unsuppressed in Dotdigital.

  • You can use either the NetSuite marketing subscriptions or a field to store opt in/out status.
  • A single configuration is used for both customer and contact entities.
  • We optionally allow the creation of a contact if we can’t find a match in NetSuite. This is to ensure that NetSuite has the opt out status for this email address.
  • Email addresses are validated prior to synchronisation. Invalid email addresses cannot be processed.

Item data for Product Catalog creation

  • The NetSuite product catalog is named in this format:
    catalog_<Parent company name><Company name><Country code>_NetSuite
    Example:
    catalog_ParentCompanyAcmeIncUS_NetSuite
  • Only active products are listed and synced initially.
  • Products that have no price mapped will not be included in the catalog.
  • When a product is flagged as inactive it will be removed from the catalog at next sync.
  • Custom multi-select fields cannot be mapped.
  • A fallback product URL can be set if we cannot map one from NetSuite.
  • A fallback product image URL can be set if we cannot map one from NetSuite.

Orders

  • Only orders that can be linked to an existing contact in Dotdigital are synced, therefore you should sync orders in conjunction with customer syncing.
  • Discount lines are summarized to the total discount amount in the field discount_amount.
  • There is now a location field in the order insight records which will provide insight to where the order was taken.

Technical notes

This section is primarily aimed at NetSuite administrators who want to understand more about how the Dotdigital NetSuite integration accesses NetSuite.

Polling based
The integration will poll hourly to detect modified records that need syncing. This is not on the hour but rather based on when a data set was last synced. If a large amount of data is being synced in a data set, such as customers during the initial sync, then other data sets will queue behind this and will not sync until completed.

It uses a single API thread
The integration runs each data set it is told to sync sequentially and only makes API calls to NetSuite single threaded, this ensures only 1 of your permitted concurrent API calls is ever utilised by the integration.

Authentication
The integration uses NetSuite’s Token Based Authentication.

To learn more about Token Based Authentication in NetSuite, check out the NetSuite article Token-based Authentication (TBA).

NetSuite data access
The integration uses the NetSuite REST API for data access. You must enroll your NetSuite account on the Oracle NetSuite Umbrella Beta Program.

The instructions for how to enroll can be found on the NetSuite help centre.

See also

Did you find this article helpful?

Can we help?

Thanks for using Dotdigital. If you need more help or support, then contact our support team.