Integrate WooCommerce with an ERP, No Lost Orders

Define Master Systems

No two systems should be authorised to change the same data without a rule that resolves the conflict.

Identifiers

Use stable keys:

• Unique SKU.
• Variation ID.
• External customer ID.
• Web order number.
• Transaction ID.
• ERP invoice number.
• Sync batch.

Names are not identifiers. A description change must not create a new product.

API and Webhooks

WooCommerce provides a REST API to read and write products, orders and other resources. Webhooks notify events to a URL.

Recommended pattern:

1. The webhook reports the event.
2. The receiver validates the signature and logs the event.
3. A queue decouples processing.
4. A worker fetches the detail via the API.
5. The data is transformed and sent to the ERP.
6. The result is confirmed.
7. Reconciliation catches anything missing.

Don't rely on the webhook alone: it can fail or be disabled after repeated errors. Periodic reconciliation is mandatory.

Security

• Separate keys per integration and environment.
• Least privilege.
• HTTPS.
• Secrets in a vault, not in code.
• Rotation.
• IP restrictions or extra controls where relevant.
• Logs without secrets.
• Payload validation.
• Replay protection.
• WordPress and plugins kept patched.

The official documentation shows keys with read and write permissions; grant them only if the flow requires it.

Orders and Statuses

Map each status:

The mapping is adapted to the gateway and logistics. Never invoice on an ambiguous status.

Idempotency

Each event has a composite key — store, order, type and version. If it arrives twice, the second operation updates or is ignored; it never creates another order.

Retries after a timeout first check whether the operation already exists.

Stock

Define:

• Physical stock.
• Reserved.
• Available to sell.
• Safety stock.
• Backorder.
• Multiple warehouses.
• Kits and variations.

The store should receive the available figure, not necessarily the physical one. Frequency depends on turnover and the risk of overselling.

Reconcile by SKU and alert on discrepancies.

Pricing and Promotions

Decide where prices, coupons, taxes and rounding live. The ERP receives enough of a breakdown to reproduce the total.

Complex promotions can be logged as a traceable discount. Don't recalculate in the ERP in a way that changes what was charged.

Taxes

Test B2C/B2B, territories, exemptions, rates, shipping costs and discounts. Tax localisation and invoicing obligations must be validated.

WooCommerce calculates the sale; the ERP must accept or validate it per the design, without creating silent discrepancies.

Customers and Privacy

For guest checkout, avoid creating duplicates for every variant of an email address. Define a matching rule and when to update the data.

The integration minimises data, controls roles and contracts, and applies retention limits. Marketing isn't triggered automatically by a purchase.

Invoices

The ERP usually numbers and issues invoices. The link returns the number, PDF or status to WooCommerce or the customer area. Credit notes and returns are linked to the original.

An issued invoice is never edited for an order change; the correct tax procedure applies instead.

Payments

The order, the transaction and the settlement are distinct objects. Reconcile:

• Order amount.
• Charge.
• Fee.
• Refund.
• Chargeback.
• Bank settlement.

An order webhook doesn't prove the money has settled.

Shipping and Returns

The ERP/WMS sends carrier, tracking, parcels and status. Returns generate authorisation, receipt, inspection, credit and restocking depending on condition.

Stock isn't restocked when a return is requested; it's restocked once received and validated.

Error Handling

The error queue shows:

• Event.
• Order/SKU.
• Cause.
• Retries.
• Last response.
• Owner.
• Action.

Permanent errors — for example, a non-existent SKU — are not retried indefinitely. Fix the data and reprocess.

Observability

Metrics:

• Orders synced.
• p95 latency.
• Errors by cause.
• Retries.
• Stock discrepancies.
• Orders without an invoice.
• Payments without an order.
• Inactive webhooks.
• Duplicates avoided.

Alerts must be actionable.

Testing

• Guest and account order.
• Variations.
• Coupon.
• Multiple taxes.
• Failed payment.
• Partial refund.
• Cancellation.
• Concurrent stock.
• Duplicate webhook.
• ERP down.
• WooCommerce down.
• SKU change.
• Return.

Rollout Plan

Days 1–30

Masters, statuses, taxes, architecture and security.

Days 31–60

API, webhooks, queues, idempotency and testing.

Days 61–90

Pilot, reconciliation, alerts and production.

Common Mistakes

1. No master source.
2. Using names as keys.
3. Relying only on webhooks.
4. Retrying without idempotency.
5. No error queue.
6. Updating physical stock.
7. Recalculating promotions.
8. Invoicing before a valid payment.
9. Restocking before the return is received.
10. No daily reconciliation.

Checklist

• Masters.
• Identifiers.
• Statuses.
• Idempotency.
• Available stock.
• Pricing and taxes.
• Customers and privacy.
• Invoices and payments.
• Errors and alerts.
• Reconciliation and rollback.

Frequently Asked Questions

API or Plugin?

It depends on the scope. A plugin can speed things up, but it must demonstrate security, maintenance, idempotency and support.

Are Webhooks Enough?

No. They must be complemented with polling and reconciliation.

Who Should Control Stock?

Usually the ERP/WMS. WooCommerce receives the calculated availability.

Official Sources Consulted

• WooCommerce REST API.
• WooCommerce Webhooks.
• WooCommerce Developer REST API.
• WooCommerce: working with webhooks.

Summum Sistemas can design the integration, the queues, the reconciliation and the monitoring.