Complete WooSync Setup Guide - From Install to First Sync

Last updated on Aug 23, 2026 5:31 PM 5:31 PM 622.09 ms

Before You Start

You’ll need:

Perfex CRM 3.4.0 or later
At least one WooCommerce store with REST API enabled
Admin access to both systems

Total setup time: 10 - 15 minutes.

Step 1: Install the Module

WooSync creates 16 database tables automatically on activation - no manual SQL needed.

Step 2: Generate WooCommerce API Keys

Step 3: Add Your Store in Perfex CRM

Step 4: Configure Webhooks (Real-Time Sync)

After saving your store, edit it to see the Webhook Delivery URL and Webhook Secret.

In WooCommerce:

Go to Settings → Advanced → Webhooks Create webhooks for these events:

Event	Topic
Order created	`order.created`
Order updated	`order.updated`
Product created	`product.created`
Product updated	`product.updated`
Customer created	`customer.created`
Customer updated	`customer.updated`

Step 5: Configure Background Cron

WooSync uses Perfex CRM’s built-in cron.php for delta sync. Ensure your server runs it regularly:

cPanel/DirectAdmin:

*/5 * * * * wget -q -O- https://your-perfex.com/cron.php

For localhost/Windows development:

Go to WooSync → Settings Enable Debug Mode WooSync will trigger pseudo-cron automatically when you browse the admin panel

Step 6: Run Your First Sync

Step 7: Configure Tax Mapping (Optional)

If you use auto-invoicing and your WooCommerce store has tax rates:

Step 8: Data Mapping & Custom Fields (Optional)

WooSync v1.2.0 introduces visual data mapping. If your checkout includes custom fields (e.g., VAT Number, Delivery Date) or if you want to track specific Coupon Codes:

Go to WooSync → Data Mapping
Select your store and map the WooCommerce custom meta keys directly to Perfex CRM Client or Invoice custom fields.

Note: WooSync fully supports 16 languages. You can change your CRM language in profile settings to instantly translate the entire WooSync interface.

Verify Everything Works

After setup, check:

Stores: Connection status shows green
Products: Your WooCommerce products appear in WooSync → Products
Orders: Recent orders are synced with correct totals
Customers: Buyers are linked to Perfex Clients
Logs: WooSync → Logs shows success entries
Webhooks: Create a test order in WooCommerce - it should appear in WooSync within seconds

Troubleshooting

Issue	Solution
Connection test fails	Verify API keys, check URL, ensure REST API is enabled in WooCommerce
Webhooks not arriving	Check WooCommerce webhook delivery logs, verify URL accessibility
Orders not syncing	Ensure cron is running, check WooSync Logs for errors
Debug mode not working	Clear browser cache, verify Debug Mode is enabled in Settings

Setup complete. Your WooCommerce store is now connected to Perfex CRM.

System Architecture & Synchronization Data Workflow

graph TD
    subgraph WooCommerce Store ["WooCommerce Store (E-Commerce Platform)"]
        WC_Order["Order Placed / Updated"]
        WC_Customer["Customer Registered"]
        WC_Product["Product / Category Created"]
        WC_Refund["Order Refund Triggered"]
        WC_HPOS["HPOS (High-Performance Order Storage)"]
    end

    subgraph SyncEngine ["WooSync Synchronization Hub Engine"]
        WH_Receiver["Inbound Webhook Receiver<br/>(HMAC-SHA256 Signature Verification)"]
        Cron_Runner["Cron Delta Sync Fallback<br/>(Scheduled Polling Runner)"]
        Queue_Log["Queue & Audit Logger<br/>(Payload Tracking & Retries)"]
        AES_Enc["AES-256-CBC Encrypted Store API Keys"]
    end

    subgraph PerfexCRM ["Perfex CRM (Enterprise Platform)"]
        CRM_Client["Clients & Contacts Database"]
        CRM_Invoice["Invoices & Line Items"]
        CRM_Item["Products, Categories & Attributes"]
        CRM_Credit["Credit Notes & Refund Records"]
        CRM_Payment["Invoice Paid Status Event"]
    end

    WC_Order -->|Real-time Inbound Webhook| WH_Receiver
    WC_Customer -->|Real-time Inbound Webhook| WH_Receiver
    WC_Product -->|Real-time Inbound Webhook| WH_Receiver
    WC_Refund -->|Real-time Inbound Webhook| WH_Receiver

    WC_HPOS -.->|Scheduled Delta Poll| Cron_Runner
    WH_Receiver --> Queue_Log
    Cron_Runner --> Queue_Log

    Queue_Log -->|Auto-Create / Link Contact| CRM_Client
    Queue_Log -->|Auto-Generate Invoice| CRM_Invoice
    Queue_Log -->|Hierarchical Catalog Sync| CRM_Item
    Queue_Log -->|Generate Credit Note| CRM_Credit

    CRM_Payment -->|Reverse Sync Engine| WC_Order

Reverse Sync Engine Workflow

graph TD
    A["Perfex CRM Invoice Marked Paid"] --> B["Woosync_reverse_sync Engine Triggered"]
    B --> C{"Check Status Mapping Configuration"}
    C --> D["Resolve WooCommerce Store ID & Order ID"]
    D --> E["Decrypt API Secret Key via OpenSSL AES-256-CBC"]
    E --> F["Initialize WooCommerce REST API Client (wc/v3)"]
    F --> G["Send PUT Request to /wp-json/wc/v3/orders/{id}"]
    G --> H{"HTTP Response 200 OK?"}
    H -->|"Success"| I["Update Store Order Status (Processing -> Completed)"]
    H -->|"Failure"| J["Log Status Exception & Enqueue into Retry Queue"]

Order-to-Invoice Conversion & HPOS Field Mapping

graph TD
    A["New Order Placed on WooCommerce Store (HPOS Order)"] --> B["Inbound Webhook order.created Listener"]
    B --> C["Verify HMAC-SHA256 Signature Secret"]
    C --> D{"Customer Email Exists in Perfex CRM?"}
    D -->|"No"| E["Auto-Create New Client Profile & Contact"]
    D -->|"Yes"| F["Link Order to Existing Client Profile"]
    E --> G["Map Billing & Shipping Location Addresses"]
    F --> G
    G --> H["Convert Store Currency & Sales Tax"]
    H --> I["Auto-Generate Perfex CRM Invoice (Unpaid)"]
    I --> J["Record Item Lines, Shipping Fee & Coupon Adjustments"]

Multi-Store Connection & Security Workflow

graph TD
    A["Admin Adds New WooCommerce Store"] --> B["Input Store URL, Consumer Key, Consumer Secret & Webhook Secret"]
    B --> C["Encrypt Credentials using OpenSSL AES-256-CBC"]
    C --> D["Persist Record in woosync_stores Table"]
    D --> E["Auto-Register Inbound Webhook Endpoints"]
    E --> F["Test Connection via WooCommerce REST Client v3"]
    F --> G{"Connection Status 200 OK?"}
    G -->|"Success"| H["Activate Store Status & Start Real-Time Sync"]
    G -->|"Failure"| I["Log Alert Error & Display Credential Warnings"]

WooSync is the ultimate synchronization bridge between your WooCommerce stores and Perfex CRM. Designed for businesses of all sizes, it brings real-time data sync capabilities to keep your CRM perfectly aligned with your eCommerce operations. Say goodbye to manual data entry and automate your workflow seamlessly.

GET STARTED