Order Synchronization

Learn how WooCommerce orders are automatically synchronized to NetSuite Sales Orders, including the complete order lifecycle from creation to completion.

How Order Sync Works

When a customer places an order in WooCommerce:

1. Order Created: Customer completes checkout in WooCommerce
2. Queue Job Added: Order is added to the synchronization queue
3. Customer Check: Plugin verifies if customer exists in NetSuite
   • If not found: Creates new NetSuite customer record first
   • If found: Uses existing customer ID
4. Sales Order Creation: Creates NetSuite Sales Order with:
   • All line items with quantities and prices
   • Shipping information and costs
   • Tax calculations
   • Discounts and coupons
   • Payment method
   • Custom fields (if mapped)
5. Reference Stored: NetSuite Internal ID saved to WooCommerce order meta
6. Status Tracking: Bidirectional status updates begin

Order Data Mapping

Order Header Fields

WooCommerce Field	NetSuite Field	Notes
Order Number	PO Number	Also stored in Memo field
Order Date	Transaction Date	Converted to NetSuite timezone
Customer ID	Customer Internal ID	Linked to NetSuite customer
Order Total	Total	Calculated from line items
Currency	Currency	Must match NetSuite currency
Order Status	Status	Mapped based on settings
Customer Note	Memo	Visible in NetSuite order
IP Address	Custom Field	If custom field mapped

Line Item Fields

WooCommerce Field	NetSuite Field	Notes
Product SKU	Item Internal ID	Matched by SKU to find NetSuite item
Product Name	Description	Overrides item description
Quantity	Quantity	Direct mapping
Price	Rate	Unit price per item
Line Total	Amount	Calculated: Quantity × Rate
Tax	Tax Amount	Per line item tax
Product Variations	Item Options / Description	Variation details added to description

Shipping & Tax

WooCommerce Field	NetSuite Field	Notes
Shipping Method	Ship Via	Auto-matched by name
Shipping Cost	Shipping Cost	Added as line item or header field
Shipping Address	Shipping Address	Full address fields
Tax Total	Tax Total	Sum of all line item taxes
Tax Rate	Tax Item	Matched to NetSuite tax items

Order Status Mapping

WooCommerce order statuses are mapped to NetSuite sales order statuses:

WooCommerce Status	NetSuite Status	Description
Pending Payment	Pending Approval	Order awaiting payment
Processing	Pending Fulfillment	Paid, ready to ship
On Hold	Pending Approval	Order paused
Completed	Billed	Order fulfilled and invoiced
Cancelled	Cancelled	Order cancelled
Refunded	Closed	Refund processed
Failed	Cancelled	Payment failed

Note: Status mappings are customizable in plugin settings.

Handling Special Order Types

Guest Orders

For guest checkout orders (no WooCommerce account):

• Option 1 – Create Each Time: New NetSuite customer for each order
• Option 2 – Match by Email: Search for existing customer by email, create if not found
• Option 3 – Single Guest Account: All guest orders use one NetSuite customer

Configure in: Settings > Customer Sync > Guest Customer Handling

Subscription Orders

For WooCommerce Subscriptions plugin:

• Initial order: Creates NetSuite Sales Order
• Renewal orders: Creates new Sales Orders linked to original
• Subscription meta data stored in custom fields
• Parent subscription ID included in memo

Product Bundles

For WooCommerce product bundles:

• Option 1 – Single Item: Sync bundle as one NetSuite item
• Option 2 – Expand Components: Sync individual bundle components as separate line items

Variable Products

For products with variations:

• Match variation SKU to NetSuite item
• If no variation SKU: Match parent product SKU
• Variation attributes added to line item description
• Example: “T-Shirt – Large – Blue” added to description

Custom Field Mapping

You can map custom WooCommerce order fields to NetSuite custom fields:

1. Navigate to WooCommerce > NetSuite > Field Mapping
2. Select Order Fields tab
3. Click Add Custom Mapping
4. Configure:
   • WooCommerce Field: Order meta key (e.g., _custom_field_name)
   • NetSuite Field: Custom field script ID (e.g., custbody_custom_field)
   • Data Type: String / Number / Date / Boolean
   • Transform Function: Optional PHP function to transform data
5. Click Save Mapping

Example Custom Field Mapping

// WooCommerce side
$order->update_meta_data('_delivery_date', '2024-12-25');

// Field Mapping Configuration
WooCommerce Field: _delivery_date
NetSuite Field: custbody_delivery_date
Data Type: Date
Transform: woons_format_date

// Transform function in functions.php
function woons_format_date($value) {
    return date('m/d/Y', strtotime($value));
}

Manual Order Sync

You can manually trigger order synchronization:

Via Admin Interface

1. Go to WooCommerce > Orders
2. Open the order you want to sync
3. Scroll to NetSuite Integration meta box
4. Click Sync to NetSuite button
5. View sync status and NetSuite ID after completion

Via WP-CLI

# Sync specific order
wp woons sync order 12345

# Sync all pending orders
wp woons sync orders --status=pending

# Sync date range
wp woons sync orders --from=2024-01-01 --to=2024-01-31

# Dry run (test without actually syncing)
wp woons sync orders --dry-run

Programmatically

// Sync single order
do_action('woons_sync_order', $order_id);

// Or use the API directly
$sync_handler = WooNS_Order_Sync::instance();
$result = $sync_handler->sync_order($order_id);

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

Bulk Order Operations

Sync multiple orders at once:

1. Navigate to WooCommerce > Orders
2. Select multiple orders using checkboxes
3. Choose Sync to NetSuite from Bulk Actions dropdown
4. Click Apply
5. Orders are added to queue and processed in background

Monitoring Order Sync

Order Meta Box

Each order displays a NetSuite Integration meta box showing:

• Sync Status: Pending / Synced / Failed
• NetSuite ID: Internal ID of Sales Order
• Last Sync Date: When last synchronized
• Sync Errors: Any error messages
• Quick Actions: Sync Now / View in NetSuite

Sync Log

View detailed sync history:

1. Navigate to WooCommerce > NetSuite > Sync Log
2. Filter by:
   • Date range
   • Order status
   • Sync status (success/failed)
   • Record type (order/customer/etc)
3. View details: Click on any log entry to see full API request/response

Troubleshooting Order Sync

Common Issues

Issue	Cause	Solution
Product Not Found	SKU doesn’t match NetSuite item	Verify SKU in both systems, check matching method
Customer Not Created	Missing required fields	Ensure email, name present; check NetSuite permissions
Tax Calculation Mismatch	Different tax rules	Use NetSuite tax calculation, disable WooCommerce tax sync
Currency Mismatch	Order currency not in NetSuite	Add currency to NetSuite or set default currency
Duplicate Orders	Order synced multiple times	Check for duplicate queue jobs, verify order meta

Debugging

Enable debug logging to troubleshoot issues:

1. Go to Settings > General > Enable Debug Logging
2. Check the box and save
3. Logs saved to: wp-content/uploads/wc-logs/woons-YYYY-MM-DD.log
4. Review logs for detailed API requests and responses

Best Practices

• SKU Consistency: Ensure SKUs match exactly between systems
• Test First: Test with a few orders before enabling auto-sync
• Monitor Queue: Regularly check queue for failed jobs
• Sync Timing: Use scheduled sync during off-peak hours for large volumes
• Custom Fields: Document all custom field mappings
• Error Notifications: Set up email alerts for sync failures

Advanced Order Sync

Conditional Sync

Use filters to conditionally sync orders:

// Skip orders below a threshold
add_filter('woons_should_sync_order', function($should_sync, $order) {
    if ($order->get_total() < 50) {
        return false; // Don't sync orders under $50
    }
    return $should_sync;
}, 10, 2);

// Skip specific products
add_filter('woons_should_sync_order', function($should_sync, $order) {
    foreach ($order->get_items() as $item) {
        $product = $item->get_product();
        if ($product->get_sku() === 'DIGITAL-PRODUCT') {
            return false; // Don't sync digital products
        }
    }
    return $should_sync;
}, 10, 2);

Modifying Order Data Before Sync

// Modify order data before sending to NetSuite
add_filter('woons_order_data_before_sync', function($data, $order) {
    // Add custom memo
    $data['memo'] = "WooCommerce Order #{$order->get_order_number()}";
    
    // Set specific department
    $data['department'] = ['internalId' => '5'];
    
    // Add custom field
    $data['customFieldList'] = [
        'customField' => [
            [
                'scriptId' => 'custbody_source',
                'value' => 'WooCommerce'
            ]
        ]
    ];
    
    return $data;
}, 10, 2);