Erply WooCommerce Integration V2 – Setup Guide & FAQ
Nov 4, 2026 ·
Overview
The integration connects one Erply account to up to 4 WooCommerce stores. It needs two apps from the Erply App Store, and both must be installed. If only one is installed, nothing syncs.
| App | What it is | Where you use it |
|---|---|---|
| WooCommerce Integration V2 | The interface where you connect your store, run setup, view the Dashboard and Sync Log. Also holds the built-in guide. | Open it from the App Store every time you manage the sync |
| WooCommerce Integration V2 API | The two-way sync between Erply and WooCommerce: products, stock and orders. | Install only; you don't work in it directly |
The direction of each flow:
- Erply → WooCommerce: products, stock and prices. Erply is the master.
- WooCommerce → Erply: orders, refunds, customers and, optionally, product edits.
The E-commerce Customer Matching app is installed together with the integration. It decides how web-order buyers are matched to existing Erply customers.
Step 1: Install both apps from the Erply App Store
Install both apps before you touch WooCommerce. You will find them listed next to each other in the App Store.
- Sign in to Erply and open the App Store.
- Search for WooCommerce.
- Install WooCommerce Integration V2 (purple "woo 2.0" icon).
- Install WooCommerce Integration V2 API (purple "woo API 2.0" icon).
- Check that both cards show Up to date. Each card shows its latest version number below that.
- Click Open on WooCommerce Integration V2. This is where setup starts and where the built-in guide lives.
If E-commerce Customer Matching was not installed with the integration, install it from the App Store too. Without it, customers are matched by e-mail only.
Both apps in the App Store:
Step 2: Prepare WooCommerce
Create an API key and check permalinks in WordPress before running the setup wizard.
- In WordPress, go to WooCommerce → Settings → Advanced → REST API.
- Click Add key and set permissions to Read/Write.
- Copy the Consumer Key and Consumer Secret right away. WooCommerce shows the secret only once.
- Go to Settings → Permalinks and make sure it is not set to "Plain". With Plain permalinks the WooCommerce API doesn't work and the connection test fails with a 404.
- Check WooCommerce → Settings → Tax → "Prices entered with tax". You will need to match this in the wizard's tax mode.
You don't need to add an order webhook by hand. Saving the connection in Erply registers it automatically. Remove any order webhooks left over from another integration, or orders may be duplicated.
Step 3: Run the setup wizard
Open WooCommerce Integration V2 and follow the wizard. Nothing syncs until you click Finish Setup & Start First Sync.
The wizard asks for these settings, in this order:
- Connection: store URL, Consumer Key and Consumer Secret.
- Catalog scenario: which side already has products. Choose "Erply only", "WooCommerce only" or "Both". The last two send you to Product Reconciliation (Step 5).
- Online locations: the Erply locations whose stock is shown in WooCommerce.
- Customer group and fulfillment location: where new web customers go, and which location web orders are fulfilled from.
- Price lists: optional, up to 5, in priority order.
- Tax mode: must match WooCommerce's "Prices entered with tax" setting.
- Shipping product: the Erply product used for shipping lines.
- Payment, category and brand mappings: see Step 4.
Everything can be changed later under Setup → your store. That page also holds settings the wizard skips: Field Sync, Documents, Changes Made in WooCommerce and e-mail alerts.
To connect more stores (up to 4), use the Connected Stores list. Each store has its own settings, switched with the store picker at the top of every page.
Step 4: Mappings
Mappings connect Erply values to their WooCommerce equivalents. None are required to start syncing, but unmapped values fall back to defaults.
| Mapping | Erply ↔ WooCommerce | If left unmapped |
|---|---|---|
| Category | Product Group ↔ category | The category is created in WooCommerce automatically when a product from that group first syncs |
| Payment Gateways | Payment type ↔ gateway | The order is recorded as CARD |
| Tax | VAT rate ↔ tax class | The account's default VAT rate is used |
| Brand | Brand ↔ brand | Not sent, unless Brand is on in Field Sync |
- Export to WooCommerce creates all missing categories or brands in WooCommerce at once. Brands need WooCommerce 9.6 or later. Run it before turning Brand on for a store with no brands.
- Import from WooCommerce does the opposite and creates missing Erply groups or brands.
- After changing a mapping, click Resync All Products to apply it to products already in WooCommerce.
- Payment mappings apply to new orders from then on only.
Step 5: Product Reconciliation (existing WooCommerce stores)
Skip this step if WooCommerce had no products before you connected it. Otherwise, link existing products here before Erply starts pushing.
- Keep Migration Mode on. It pauses the Erply → WooCommerce push so your import isn't overwritten. The wizard turns it on for you.
- Click Scan Now. Products that already carry an Erply ID are linked automatically. For the rest, the scan suggests an Erply product with the same barcode (EAN) or exactly the same name. SKUs are never used. Nothing in WooCommerce is changed.
- Under Needs Your Decision, for each product: Confirm the suggestion (or Confirm all suggested matches), Link to another Erply product, Import it as a new Erply product, or Ignore it.
- Click Import All Pending to import the remaining products that have no suggestion. Products with a suggestion are left for you, so nothing is duplicated.
- Optional: run Import Past Orders (see FAQ) if you want order history in Erply.
- Click Import Stock to set Fulfillment Location stock to the WooCommerce quantities. Always run this after importing past orders.
- Click Import Customers to bring in existing WooCommerce customer accounts.
- Turn Migration Mode off. Until you do, nothing is pushed to WooCommerce.
Variable products import as Erply matrix products, with up to 3 attributes. Images are copied too, if the WooCommerce host allows Erply to download them.
How the sync works
Once setup is finished, everything runs on its own schedule.
| Flow | Direction | Timing | Key rules |
|---|---|---|---|
| Products | Erply → Woo | Scheduled | Active = published, any other status = Draft. Bundles and assemblies are not sent. With an Assortment selected, only its products go to that store. |
| Stock | Erply → Woo | About 5 min; full check hourly | The hourly check also overwrites stock edited by hand in WooCommerce. Field Sync Off stops it. |
| Prices | Erply → Woo | About 15 min; list start/end within an hour | Base price unless price lists are set. Sale price and quantity discounts are not used. |
| Orders | Woo → Erply | Instant (webhook) | Order status decides Invoice, Sales Order or nothing (Documents setting). Stock is taken off when the invoice is created. |
| Refunds | Woo → Erply | With the order | Off by default. Each refund becomes a credit invoice. Money-only refunds need a Refund Product. |
| Customers | Woo → Erply | Per order; optional hourly import | Matched by E-commerce Customer Matching rules. Changes to existing customers are not synced. |
| Product edits | Woo → Erply | About 5 min | Off by default (Changes Made in WooCommerce). Deleted products are archived in Erply. Stock is never taken from WooCommerce. |
Field Sync
Field Sync (Setup → your store) decides which product fields are sent. Each field is set to one of these:
- Always: updated on every sync. Edits made in WooCommerce are overwritten.
- Only on create: set once, then left for you to edit in WooCommerce.
- Off: never sent.
Brand, EAN, short description and tax class start as Off. After changing Field Sync, click Resync all products on the Dashboard.
Additional charges
Plugin charges such as excise, payment fees, packaging or deposits don't reach Erply until mapped. Open Configuration → Additional Charges, then:
- Map each charge with Create & map, using the same VAT rate WooCommerce charges on it.
- Order rules from specific to general. The first match wins.
- Click Turn on syncing.
Once syncing is on, an order with an unmapped charge is held until you add a rule and click Retry.
Dashboard & Sync Log
The Sync Log is the first place to check when something "isn't syncing."
- Dashboard: shows the last result of each flow (Products, Stock, Prices, Orders). Sync Now pushes a change right away; otherwise everything runs on schedule. Warning banners flag unmapped categories or gateways, a missing shipping product, a currency mismatch, duplicate order webhooks, and WooCommerce products with no Erply match.
- Sync Log: every past run with its outcome and errors. Filter by flow, status or date.
- Orders That Need Attention: failed orders with the reason. Fix the cause, then click Retry. Retry never creates a second document.
- Alerts: set an alert e-mail on the store page to be notified of failures.
FAQ
Do I need both apps? Yes. WooCommerce Integration V2 is the interface you set up and monitor from. WooCommerce Integration V2 API carries out the sync. Install both from the App Store.
Where is the built-in guide? Inside WooCommerce Integration V2. Click Open on its App Store card.
Which system is the master? Erply is the master for products, stock and prices. WooCommerce sends orders, refunds and new customers to Erply.
Do I need to add a webhook in WooCommerce? No. Saving the connection registers the order webhook automatically.
How many WooCommerce stores can I connect? Up to 4. Each store keeps its own settings and mappings.
Can I edit products in WooCommerce? Only fields set to Only on create or Off in Field Sync. Fields set to Always are overwritten by Erply on the next sync.
Can I change stock in WooCommerce? No. Stock always comes from Erply. Manual changes are corrected by the hourly full check.
How quickly do changes reach WooCommerce? Stock within about 5 minutes, prices within about 15 minutes, and products on a schedule. Click Sync Now to push immediately.
Which price is shown in WooCommerce? The product's Erply base price by default. With price lists selected, the first list from the top that contains the product sets the price. Only active, in-date lists are used.
Are orders placed before setup imported? No, not automatically. Use Import Past Orders. Orders already in Erply are skipped. Run it before Import Stock; if stock was already imported, run Import Stock again afterwards.
What does each order status create in Erply? By default, processing and completed orders become invoices. Change this per status in Setup → your store → Documents.
What happens when an order is cancelled? Its Erply sales order is cancelled. If it was already invoiced, the invoice stays and the cancellation is noted in the Sync Log.
Are refunds synced? Only if turned on in the Documents card. Each refund becomes a credit invoice, and returned items go back to stock.
How are customers matched? By the rules in E-commerce Customer Matching (e-mail, phone, name). Without the app, by e-mail only. New customers go to the store's customer group.
Are staff accounts imported as customers? No.
Can I pause the sync while I prepare data? Yes. Migration Mode on the Product Reconciliation page pauses the Erply → WooCommerce push.
Troubleshooting
Check the Sync Log first, then find the symptom below.
| Symptom | Likely cause | Fix |
|---|---|---|
| Nothing syncs at all | Only one of the two apps is installed | Install both WooCommerce Integration V2 and V2 API |
| Connection test fails with 404 | Permalinks set to "Plain", or key/secret copied incompletely | Change permalinks in WordPress; re-copy the key and secret |
| Nothing reaches WooCommerce | Migration Mode is on, or products aren't Active or in the store's assortment | Turn Migration Mode off; check product status and assortment |
| Order refused | No shipping product, or store currency differs from Erply's | Check the reason on the Orders page, fix it, then Retry |
| Order created nothing | That status is set to "Nothing" in Documents | It is created once the order reaches a status that creates a document |
| Order held | An additional charge matches no rule | Add or adjust a rule in Additional Charges, then Retry |
| No credit invoice for a refund | Refunds are off, or a money-only refund has no Refund Product | Turn refunds on in Documents; set a Refund Product |
| Every order creates a new customer | No enabled rules in E-commerce Customer Matching | Add at least an e-mail rule |
| All prices off by the VAT rate | Price Tax Mode doesn't match WooCommerce's "Prices entered with tax" | Make the two settings match |
| Invoice total differs by the tax | Order taxed at a rate Erply doesn't have | Add that VAT rate in Erply, delete the document, use Import an Order Again |
| Invoice total lower than the order | Additional charges not mapped or syncing off | Map the charges and turn syncing on |
| Price list price not shown | List inactive or out of date, product not linked, or a higher list contains it | Check list status and dates, the link, and priority order |
| WooCommerce edit overwritten | Field set to Always in Field Sync | Change it in Erply, or set the field to Only on create |
| Duplicate orders | Another integration's webhook still active | Follow the warning banner to Setup → Advanced and remove it |
| Sync shows "Stalled" | Nothing updated for 3 minutes | Click Sync Now to restart; nothing already synced is lost |