WooCommerce to Microsoft Dynamics: field mapping and sync guide

The WooCommerce side uses the REST API v3. The Dynamics side uses the Business Central API v2.0, because it has one documented resource for each thing a store needs. If you run Dynamics 365 Sales or Finance, the logic holds and the names differ; our product comparison covers those.

We have delivered order and customer sync between WooCommerce and Dynamics on a high-volume Belgian store, and enquiries and customer data from WordPress into Dynamics for a water-treatment supplier. Most of our work is delivered under NDA, so many projects cannot be named. Product and invoice mappings come from the documentation, and we say so here rather than imply otherwise. Treat this as a starting point to check on your own environment, because Dynamics customisation can change which fields exist and which are required.

1. Who owns each record. For each field, one system is the source of truth. If you can’t say which, you will end up with both systems overwriting each other.
2. The shared key. SKU for products, order number for orders, and your own lookup table for customers. A store and an ERP have different internal IDs, and neither should have to remember the other’s.
3. When an order becomes real. Most stores should send an order when payment is confirmed, not when it is created. Otherwise abandoned payment attempts turn into sales documents someone has to clean up.

Usually one way, store to Dynamics, with status coming back. See the Woo order properties, salesOrder and salesOrderLine.

Status mapping

Woo has seven standard statuses, and a Business Central sales order only reports Draft, In Review or Open, plus a fullyShipped flag. So status isn’t a field-to-field copy. A workable rule looks like this:

Tax and rounding

Don’t expect totals to match by chance. Woo calculates tax by its own settings, and Dynamics recalculates from its own tax setup, so a 0.01 difference on a multi-line order is common. Decide the tolerance with finance, and compare total and total_tax with totalAmountIncludingTax and totalTaxAmount after creation. Anything outside the tolerance should raise an alert rather than quietly post.

See Woo customers and the customer resource. Many B2C stores send every order to a single “web customer” in Dynamics, with the address on the order, and only create named customers for accounts. That is a legitimate choice and removes a lot of matching logic, but check that finance and your VAT reporting can live with it.

Usually Dynamics to store. See Woo products and the item resource. Keep descriptions, images and SEO fields in WooCommerce unless you have a reason not to, since an ERP is a poor place to write them.

Stock is where timing matters most. Dynamics’ figure doesn’t know about orders that haven’t reached it yet, so a naive overwrite can put units back on sale. Either subtract orders in flight or accept and document a small overselling risk.

Let Dynamics issue invoices, and let the store only display them. The shipAndInvoice action on a sales order and the post action on a salesInvoice are how documents become final. Microsoft notes that the id on this resource can differ from the record’s systemId once posted, so store the API id and don’t assume they match.

Use both. Webhooks give you speed, and a scheduled job gives you certainty. Here is what each side actually does.

Three things follow from that table.

• Answer webhooks fast. Accept, store the message, reply with a 2xx, and do the work in a queue. A slow receiver is how a Woo webhook gets disabled, and at that point nothing announces that orders have stopped flowing.
• Return a retryable error. If your receiver is having trouble with Business Central notifications, send a 503 and not a 400. The wrong error code deletes your subscription.
• Renew on a schedule, and monitor it. A forgotten three-day renewal is a silent failure.

Then add a scheduled job as the safety net. Ask each system for what changed since the last run, using modified_after on WooCommerce and a filter on lastModifiedDateTime on Business Central, and process anything the webhooks missed. Because the job can run again safely, it also repairs an outage without anybody having to work out what was lost.

Avoid “last write wins” unless a field really doesn’t matter. Clocks differ, and a bulk update in Dynamics can overwrite a customer’s address from an hour ago. Here is a starting point to adapt.

• Business Central rate limits. Microsoft lists 6,000 OData requests in a five-minute window per user, 5 processed at once, 100 operations in a batch, and an 8-minute timeout. Exceeding the rate limit returns a 429, so retries need a wait.
• Woo batch limit. Batch endpoints such as products take up to 100 objects per request by default.
• Custom fields. Microsoft says standard API pages can’t be extended with extra fields. To send a payment reference, you copy the page’s AL code into a custom API, which is routine but needs someone who can write AL.
• Order storage. Stores can use High-Performance Order Storage, on by default for new installs since WooCommerce 8.2. Integration code that reads order data straight from the posts tables will break there, so use the REST API or the order classes.

For how this holds up under load, read syncing orders at high volume. If you would like us to build it, see the integration service. For the store itself, see WooCommerce development.