how to sync woocommerce orders into an erp without retyping

why woocommerce orders still get retyped into the erp

Finance still opens WooCommerce, copies the order number into Comarch Optima, enova365 or Subiekt GT, then retypes NIP, shipping address and every line. That routine breaks the moment a customer edits the shipping method after payment, a partial refund lands, or a bundle SKU in the shop does not exist as a card in the ERP. The spreadsheet bridge that worked at fifty orders a month collapses at a few hundred: two people edit the same CSV, VAT rates diverge, and the warehouse picks from a status that accounting never posted. The deeper cost is not typing time. It is disputed invoices, stock that ERP thinks is free while the shop already sold it, and month-end closes that wait on a human to reconcile payment gateway fees with document numbering. Agencies that wire shops under NDA see the same pattern repeatedly: the shop is the commercial front, the ERP is the legal ledger, and nothing trustworthy sits between them except tribal knowledge about which custom field means which warehouse and which payment method maps to which cash register. Without an automation contract you also lack idempotency. Refreshing the thank-you page or a webhook retry creates a second ERP document for the same WooCommerce ID. Staff then void documents by hand, which creates audit noise and breaks sequential numbering rules some accountants treat as sacred. Multilingual B2B shops make it worse: billing company on the order is a VAT group, ship-to is a branch, and the ERP expects both as linked contractors before a sales order can post. Marketplace orders forwarded into WooCommerce add yet another external ID that must stay correlated so returns find the right fiscal document. Currency and tax edge cases pile on. A EUR checkout against a PLN company in Optima needs an explicit rate source and posting date. Reduced VAT on books or food in one locale must not silently fall back to the standard rate because the tax class string in WooCommerce was renamed during a theme cleanup. Shipping as a separate taxable service versus freight baked into the line total changes how enova expects the document schema. Gift cards, store credit and wallet top-ups often must never create stock movements, yet they still need a financial document or they vanish from revenue reports. A durable fix treats the paid WooCommerce order as an event, maps SKUs and tax classes explicitly, writes one ERP document per shop order ID, and mirrors status changes back so support never promises a shipment the ledger has not accepted. That is the gap this use case closes: not a fancy dashboard, but a reliable hand-off from cart to accounting document with clear ownership when mapping fails and a reconcile path when webhooks were missed overnight. Operator runbooks should name the person who owns SKU tax maps, the person who clears dead-letter orders, and the escalation path when a fiscal period is closed in the ERP. Peak-season drills that replay yesterday's paid orders into a sandbox company in Optima or enova catch mapping drift before it hits live document numbers. Keep a written matrix of payment methods to cash registers so a new gateway does not silently post into the wrong till.

when a paid woocommerce order should create an erp document

Fire on WooCommerce `order.paid` or `payment_complete`, and again on `order.updated` when shipping address, line items or status move after the first successful ERP write. Also schedule a fifteen-minute reconcile that lists paid orders missing an ERP document ID in order meta, covering webhook outages and admin-created orders. Do not trigger on `pending` or `on-hold` unless your policy books reservations before capture; most Polish and DACH merchants wait for captured payment so Optima or enova does not create receivables that never clear. Subscription renewals should use the renewal order ID as the correlation key, not the parent subscription ID alone.

steps to map woocommerce line items into erp sales documents

1. Validate the order: required billing fields, NIP or VAT ID format for B2B, currency allowed by the ERP company, and every line SKU present in the mapping table. Reject with a structured error if a gift-card or virtual line has no ERP article and your policy forbids silent skips. Record the validation fingerprint so identical retries short-circuit.
2. Upsert the contractor in the ERP. Match on NIP first, then email, then create with billing address. Attach ship-to as a secondary address when Subiekt or Optima models branches separately from the legal buyer. Preserve the WooCommerce customer ID as an external key for later deduplication.
3. Build the sales document: map line items, tax rates, shipping as a service line or freight field, coupons as discounts with the same tax treatment the shop used, and payment method to the ERP cash register or bank account code. Include marketplace fees as cost lines only when finance asks for them on the same document.
4. Post or save the document according to company rules, store the ERP document number and internal ID in WooCommerce order meta, and mark a sync state of `posted`, `draft`, or `needs_mapping` so support can see it without opening the ERP. Emit an internal event for warehouse or WMS listeners.
5. On later refunds or cancellations, create the matching credit note or cancel document linked to the original ERP ID. Never invent a new sales document for a refund event. Push ERP document status back to a custom order status or note when warehouse posting completes, including partial fulfilments when the ERP supports them.

how webhooks n8n and erp apis carry the order payload

Prefer WooCommerce webhooks into n8n for near-real-time hand-off, with Action Scheduler or WP-Cron as a safety net when the webhook endpoint was down. n8n holds the mapping tables, retries and dead-letter queue; direct custom PHP is fine for a single Optima company with stable SKUs, but it ages poorly when you add enova for a second legal entity. Payload shape is shop order JSON normalised to an internal DTO: buyer, lines, taxes, payments, and correlation IDs. The ERP connector then speaks Optima API, enova web services, or a Subiekt partner API or SQL procedure - pick one connector per company code and never share tokens across companies. Secrets live outside the WordPress database in the automation host vault. Status callbacks from ERP, when available, update order meta only; they do not invent new shop orders. Google Sheets is acceptable as an operator view of failures, not as the system of record. For high volume, batch the reconcile scan but keep the paid-order path one document at a time to preserve idempotency keys.

what to do when erp rejects a woocommerce order sync

Classify failures: validation (bad NIP, missing SKU), transport (timeout, 429), and business rejects (contractor blocked, period closed). Validation errors open a Slack or email ticket with the order link and never auto-retry until mapping is fixed. Transport errors retry with exponential backoff and jitter up to a capped count, then dead-letter. Business rejects freeze the order in `needs_erp_review` and notify finance; do not keep hammering a closed fiscal period. Always key writes by WooCommerce order ID so retries stay idempotent. Log request and response hashes without storing full card data or raw PESEL if it ever appears in custom fields. If the ERP accepted the document but the shop failed to save meta, a reconcile job must detect the orphan by searching ERP for the external ID rather than posting again. Surface a weekly digest of dead-letter age so silent queues do not rot for a month.

when manual erp entry is still cheaper than order sync

Under roughly eighty paid orders a month with a single SKU list that never changes, a trained clerk in Optima may still be cheaper than building and supervising connectors. Also skip if the ERP project is mid-migration and document schemas change weekly - you will automate chaos. Pure dropshipping where the supplier invoices the customer directly often needs a different document flow than a classic sales order in Subiekt, so do not force this pattern onto that model.

kpis that show woocommerce to erp sync is healthy

• Median minutes from payment_complete to ERP document ID stored on the order
• Share of paid orders older than one hour without an ERP document ID
• Count of duplicate ERP documents traced to the same WooCommerce order ID per month
• Share of sync attempts ending in needs_mapping versus posted