Customer Synchronization

This guide explains how WooCommerce customers are synchronized with NetSuite, including bidirectional sync capabilities, guest customer handling, and address management.

Customer Sync Overview

Customer synchronization ensures that customer information is consistent across WooCommerce and NetSuite:

• WooCommerce to NetSuite: New customers are created in NetSuite automatically
• NetSuite to WooCommerce: NetSuite customer updates can sync back (optional)
• Before Orders: Customers are created/verified before order sync
• Address Sync: Billing and shipping addresses synchronized
• Guest Support: Flexible handling for guest checkout customers

When Customer Sync Occurs

Customers are synchronized in these scenarios:

1. New Account Creation: When customer registers on WooCommerce
2. Order Placement: Before syncing order (if customer doesn’t exist in NetSuite)
3. Profile Update: When customer updates their account details
4. Manual Sync: Via admin interface or WP-CLI
5. Scheduled Sync: Bulk sync via cron job (if enabled)

Customer Data Mapping

Core Customer Fields

WooCommerce Field	NetSuite Field	Sync Direction
user_email	email	Bidirectional
first_name	firstName	Bidirectional
last_name	lastName	Bidirectional
billing_company	companyName	Bidirectional
billing_phone	phone	Bidirectional
User ID	externalId	WooCommerce → NetSuite
Customer Meta	Internal ID	Stores NetSuite ID in WooCommerce

Address Fields

WooCommerce Field	NetSuite Address Field	Notes
billing_address_1	addr1	Street address line 1
billing_address_2	addr2	Street address line 2
billing_city	city	City name
billing_state	state	State/Province code
billing_postcode	zip	Postal/ZIP code
billing_country	country	Country code (US, CA, etc)

Note: Shipping address fields map identically to NetSuite shipping address fields.

NetSuite-Specific Fields

NetSuite Field	Default Value	Configurable
subsidiary	From plugin settings	Yes
terms (Payment Terms)	From plugin settings	Yes
category (Customer Type)	From plugin settings	Yes
status	CUSTOMER-Closed Won	Yes
isPerson	true (if no company name)	Auto
taxable	true	Yes

Guest Customer Handling

WooCommerce allows guest checkout (no account required). The plugin offers three strategies:

Strategy 1: Create Each Time

• Behavior: New NetSuite customer created for every guest order
• Pros: Accurate customer tracking, maintains order history per transaction
• Cons: Can create duplicate customer records if same person orders multiple times
• Best For: B2C stores with primarily one-time customers

Strategy 2: Match by Email (Recommended)

• Behavior: Search NetSuite for customer by email; create only if not found
• Pros: Prevents duplicates, consolidates customer history
• Cons: Slightly slower (requires search API call)
• Best For: Most stores, especially with repeat customers

Strategy 3: Single Guest Account

• Behavior: All guest orders assigned to one NetSuite “Guest Customer” account
• Pros: Fast, no customer searches needed
• Cons: Loses individual customer tracking, all guests appear as one customer
• Best For: High-volume stores where individual guest tracking isn’t needed

Configure in: Settings > Customer Sync > Guest Customer Handling

Customer Matching Logic

When syncing a customer, the plugin determines if they already exist in NetSuite:

1. Check WooCommerce Meta: Does this user have a stored NetSuite ID?
   • If yes: Use that NetSuite customer
   • If no: Continue to step 2
2. Search by External ID: Search NetSuite for customer with externalId = WooCommerce User ID
   • If found: Link and use that customer
   • If not found: Continue to step 3
3. Search by Email: Search NetSuite for customer with matching email
   • If found: Link and use that customer
   • If not found: Create new customer

Bidirectional Sync

You can enable bidirectional customer synchronization to keep NetSuite as the master data source:

NetSuite to WooCommerce

When enabled, changes in NetSuite customer records sync back to WooCommerce:

• Name Updates: First/last name changes
• Contact Info: Email, phone updates
• Addresses: Billing and shipping address changes
• Custom Fields: Any mapped custom fields

Configuration

1. Go to Settings > Customer Sync
2. Set Sync Direction to “Bidirectional”
3. Configure sync frequency (Hourly / Daily)
4. Save settings

Conflict Resolution

When data differs between systems:

Scenario	Resolution	Configurable
Both systems modified	NetSuite wins (default)	Yes
Field empty in NetSuite	Keep WooCommerce value	Yes
Field empty in WooCommerce	Update from NetSuite	Yes

Manual Customer Sync

Via Admin Interface

Sync individual customers:

1. Navigate to Users > All Users
2. Hover over user and click Edit
3. Scroll to NetSuite Integration section
4. Click Sync to NetSuite button
5. View NetSuite Internal ID and last sync date

Via WP-CLI

# Sync specific customer
wp woons sync customer 123

# Sync all customers
wp woons sync customers

# Sync customers created in date range
wp woons sync customers --from=2024-01-01 --to=2024-01-31

# Pull updates from NetSuite
wp woons sync customers --direction=from-netsuite

# Dry run
wp woons sync customers --dry-run

Programmatically

// Sync single customer
do_action('woons_sync_customer', $user_id);

// Or use API directly
$sync_handler = WooNS_Customer_Sync::instance();
$result = $sync_handler->sync_customer($user_id);

if ($result['success']) {
    $netsuite_id = $result['netsuite_id'];
    echo "Customer synced! NetSuite ID: {$netsuite_id}";
}

Bulk Customer Operations

Sync multiple customers at once:

1. Navigate to WooCommerce > NetSuite > Tools
2. Select Bulk Customer Sync
3. Choose criteria:
   • All customers
   • Customers without NetSuite ID
   • Customers created after specific date
   • Customers with orders in date range
4. Click Start Bulk Sync
5. Monitor progress in queue dashboard

Custom Field Mapping

Map custom WooCommerce user meta to NetSuite customer fields:

1. Navigate to WooCommerce > NetSuite > Field Mapping
2. Select Customer Fields tab
3. Click Add Custom Mapping
4. Configure mapping:
   • WooCommerce Field: User meta key
   • NetSuite Field: Custom field script ID
   • Sync Direction: To NetSuite / From NetSuite / Bidirectional
   • Transform Function: Optional data transformation

Example Custom Mapping

// Store customer tax ID in WooCommerce
update_user_meta($user_id, 'tax_id', 'TAX123456');

// Field Mapping Configuration
WooCommerce Field: tax_id
NetSuite Field: custentity_tax_id
Sync Direction: Bidirectional
Transform: strtoupper

// Tax ID syncs to NetSuite in uppercase

Address Management

Multiple Addresses

NetSuite supports multiple addresses per customer. The plugin handles:

• Default Billing: Synced as NetSuite default billing address
• Default Shipping: Synced as NetSuite default shipping address
• Additional Addresses: Order-specific addresses added as new address records

Address Book Sync

If customer uses different shipping addresses across orders:

1. First order: Creates default billing and shipping addresses
2. Second order with new address: Adds new address to NetSuite address book
3. Future orders: Reuses existing addresses if they match

Address Validation

Enable address validation to ensure data quality:

1. Go to Settings > Customer Sync > Validate Addresses
2. Check Enable Address Validation
3. Invalid addresses are logged and sync is skipped

Customer Groups & Types

Map WooCommerce customer roles to NetSuite customer types:

WooCommerce Role	NetSuite Customer Type	Configurable
Customer	Default Customer Type	Yes
Subscriber	Subscriber Type	Yes
Wholesale Customer	Wholesale Type	Yes
VIP	VIP Type	Yes

Configure in: Settings > Customer Sync > Role Mapping

Monitoring Customer Sync

User Profile Meta Box

Each WooCommerce user shows NetSuite integration status:

• NetSuite ID: Internal ID of NetSuite customer
• Last Synced: Date/time of last sync
• Sync Status: Success / Failed / Pending
• Quick Link: View customer in NetSuite

Sync Log

View customer sync history:

1. Navigate to WooCommerce > NetSuite > Sync Log
2. Filter by Record Type: Customer
3. View all customer sync attempts with results

Troubleshooting Customer Sync

Issue	Cause	Solution
Duplicate Customers	Email search not enabled	Enable “Match by Email” strategy
Missing Email Error	Guest order without email	Ensure email field is required at checkout
Address Format Invalid	International address format	Enable address validation, check country codes
Customer Not Found	NetSuite ID stored but customer deleted	Clear NetSuite ID meta, re-sync customer
Permission Error	NetSuite role lacks customer permissions	Grant “Customer: Full” permission to role

Best Practices

• Guest Strategy: Use “Match by Email” for most stores
• Regular Audits: Periodically check for duplicate customers
• Address Quality: Enable address validation
• Bidirectional Sync: Only enable if NetSuite is master data source
• Custom Fields: Document all custom field mappings
• Data Privacy: Comply with GDPR/privacy laws when syncing customer data

Advanced Customer Sync

Filter Customer Data Before Sync

// Modify customer data before syncing to NetSuite
add_filter('woons_customer_data_before_sync', function($data, $user_id) {
    // Set specific subsidiary based on country
    $country = get_user_meta($user_id, 'billing_country', true);
    if ($country === 'CA') {
        $data['subsidiary'] = ['internalId' => '2']; // Canada subsidiary
    }
    
    // Add custom field
    $data['customFieldList'] = [
        'customField' => [
            [
                'scriptId' => 'custentity_source',
                'value' => 'WooCommerce Store'
            ]
        ]
    ];
    
    return $data;
}, 10, 2);

Conditional Customer Sync

// Only sync customers who have placed orders
add_filter('woons_should_sync_customer', function($should_sync, $user_id) {
    $customer = new WC_Customer($user_id);
    $order_count = $customer->get_order_count();
    
    if ($order_count === 0) {
        return false; // Don't sync customers with no orders
    }
    
    return $should_sync;
}, 10, 2);