Sales Order Sync

Background Job

Every hour, a background task runs that performs the following steps:

1. Retrieve a list of WooCommerce Orders that have been modified since the Last Syncronisation Date (on WooCommerce Integration Settings)
2. Retrieve a list of ERPNext Sales Orders that are already linked to the WooCommerce Orders from Step 1
3. Retrieve a list of ERPNext Sales Orders that have been modified since the Last Syncronisation Date (on WooCommerce Integration Settings)
4. If necessary, retrieve a list of WooCommerce Orders that are already linked to the ERPNext Sales Orders from Step 3
5. Compare each WooCommerce Order with its ERPNext Sales Orders counterpart, creating an order if it doesn't exist

Hooks

• Every time a Sales Order is submitted, a synchronisation will take place for the Sales Order if:
  • A valid WooCommerce Server and WooCommerce ID is specified on Sales Order

In order to make this work you need to configure the webhook in both, ERPNext and WooCommerce:

1. From ERPNext you need to get the access keys from the Woocommerce server configuration, in the WooCommerce Webhook Settings.
2. Create the webhook inside WooCommerce using the "Order created" topic and the rest of the data obtained on step 1.

Manual Trigger

• Sales Order Synchronisation can also be triggered from an Sales Order, by changing the field WooCommerce Status
• Sales Order Synchronisation can also be triggered from an Sales Order, by clicking on Actions > Sync this Item with WooCommerce
• Sales Order Synchronisation can also be triggered from a WooCommerce Order, by clicking on Actions > Sync this Order with ERPNext

Background Job

Every hour, a background task runs that performs the following steps:

1. Retrieve a list of WooCommerce Orders that have been modified since the Last Syncronisation Date (on WooCommerce Integration Settings)
2. Compare each WooCommerce Order with its ERPNext Sales Order counterpart, creating a Sales Order if it doesn't exist or updating the relevant Sales Order

Synchronisation Logic

When comparing a WooCommerce Order with it's counterpart ERPNext Sales Order, the date_modified field on WooCommerce Order is compared with the modified field of ERPNext Sales Order. The last modified document will be used as master when syncronising

Note that if sync for an Item is disabled (i.e. the "Enabled" checkbox on the Item's WooCommerce Server row is unchecked) and an WooCommerce Order is placed for this item, synchronisation will be re-enabled for this item.

Fields Mapping

WooCommerce	ERPNext	Note
billing	Address with type Billing	See Customer Synchronisation below. Checks if the billing.email field matches an existing Customer's woocommerce_identifier field. If not, a new Customer is created.
	Contact
shipping	Address with type Shipping	See Address Synchronsation below
line_items	Item	Checks if a linked Item exists, else a new Item is created
id	Sales Order > Customer's Purchase Order
	Sales Order > Woocommerce ID
currency	Sales Order > Currency
customer_note	Sales Order > WooCommerce Customer Note
	Sales Order > Price List	The Customer's Default Price List, or its Customer Group's, when that list is priced in the order's currency. Otherwise the Selling Settings default is kept.

Custom Fields Mapping for Sales Order Items

You can use JSONPath to map Sales Order Item fields to specific WooCommerce Order Line Item fields.

Here are a few examples:

• $.tax_class retrieves the content of the 'Tax Class' WooCommerce Order Line Item field.
• $.meta_data[?(@.key=='my_metadata_field')].value retrieves the value of a Metadata entry with a key of my_metadata_field

where $ refers to the WooCommerce Order Line object

To figure out the correct JSONPath expression, you can:

1. Go to any WooCommerce Order and look at the 'Line Items' data
2. Open JSONPath Online Validator and copy the relevant 'Line Items' data from the WooCommerce Order to the Document text box.
3. Play around to get the JSONPath Query to return what you need. LLM's can be a big help here.

**Note that this is recommended for advanced users only. This is a very basic functionality - there are no field type conversions possible as of yet.

Customer Synchronisation

Each Customer record has a woocommerce_identifier custom field. This identifier is set depending on if the WooCommerce Order is from a guest or not:

Case	woocommerce_identifier
Company (billing.company on WooCommerce Order is set), Only if Enable Dual Accounts for Same Email (Private/Company) is checked	{billing.email}-{company}
Individual (billing.company on WooCommerce Order is not set)	billing.email
Guest with no email address at all	Guest-{order_id}

ERPNext Customer records are created as Individual by default. If the WooCommerce Order company field contains a value other than "Private" or "Pvt", the Customer record is created as Company instead.

Matching an existing Customer

Guest orders are keyed on their email address like any other order. Only a guest who gave no email at all falls back to Guest-{order_id}, which can never match another order.

When no Customer carries the identifier, synchronisation looks for an existing one before creating a new record:

1. A Customer whose woocommerce_identifier is that email address
2. A Customer linked to a Contact that holds that email address
3. A Customer already ordering from the same company email domain, if that domain is listed under WooCommerce Server > Customers Sync > Match Customers by Email Domain

A Customer found this way is linked to, not rewritten: its name and identifier are left as they are, because renaming a Customer renames it on every document it already appears on.

Enable Dual Accounts for Same Email (Private/Company) is unaffected. Where it is on and the order carries a company, only the exact identifier and a listed company domain are considered - matching on the email address alone would defeat the split it exists to create.

Matching by email domain

List one company email domain per line, e.g. acme.co.za, to put every buyer at that company on one Customer. Only listed domains are matched, deliberately: most customers order from a free mail provider, so matching every domain would put all of them on a single account.

Finding existing duplicates

Earlier versions created a new Customer for every guest order. The WooCommerce Duplicate Customers report groups Customer records that look like the same buyer - by email address, by company email domain, or by name - with order counts and values so that the record worth keeping is obvious. It only reports; use Merge with on the Customer form to act on a group.

Group by Email first: an address identifies one buyer, so those groups need no judgement. Name is the widest net and the noisiest.

When grouping by Email Domain, the Ignore Email Domains filter holds the providers whose address says nothing about who the customer is. It defaults to the global providers only - add the ISPs and regional providers your customers use, or every buyer on one of them is reported as a group.

Contact Synchronisation

Contact records are also created for Customers. In order to prevent duplicate Contacts, synchronisation checks for an existing Contact, first by the provided email address, then by provided phone number.

Currently, Contact records are not updated when details change. Changes must be handled manually.

Address Synchronisation

• If the billing and shipping address on the WooCommerce Order is the same, a single Address will be created with both the Preferred Billing Address and Preferred Shipping Address checkboxes ticked.
• If an address with Preferred Billing Address/Preferred Shipping Address ticked aleady exists, this address will be updated

Shipping Rule Synchronisation

• You can enable the synchronisation of WooCommerce Shipping Methods to ERPNext Shipping Rules on Sales Orders
• For this to work, you have to map WooCommerce Shipping Methods to ERPNext Shipping Rules
  • You can find the WooCommerce Shipping Method Title fields by looking at the method_title values in WooCommerce Order > Shipping Lines

Automatic Order Status Synchronisation

⚠️ This setting is Experimental. Monitor your Error Log after enabling this setting

• You can enable the synchronisation of ERPNext Order Status to WooCommerce Order Status by checking the "Keep the Status of ERPNext Sales Orders and WooCommerce Orders in sync" checkbox
• For this to work, you have to map ERPNext Sales Order Statuses to WooCommerce Sales Order Statuses
• For example, if you map On Hold (ERPNext Sales Order Status) to on-hold (WooCommerce Sales Order Status), if you change a Sales Order's status to On Hold, it'll automatically attempt to set the WooCommerce Order's status to On Hold

Troubleshooting

• You can look at the list of WooCommerce Orders from within ERPNext by opening the WooCommerce Order doctype. This is a Virtual DocType that interacts directly with your WooCommerce site's API interface
• Any errors during this process can be found under Error Log.
• You can also check the Scheduled Job Log for the sync_sales_orders.run_sales_orders_sync Scheduled Job.
• A history of all API calls made to your Wordpress Site can be found under WooCommerce Request Log (Enable WooCommerce Request Logs needs to be turned on on WooCommerce Server > Logs)