Tutorial

Configure ClickSync like a pro. Learn how to connect ClickUp, set up triggers, map fields, and automate your operations backend.

Understanding the ClickSync Mapping Principle

ClickSync builds an instantaneous, rule-based bridge between your WooCommerce store operations and your ClickUp tasks. Here is a high-level overview of how WooCommerce's e-commerce structure corresponds to your ClickUp workspaces:

WooCommerce Store ➔ ClickUp Team

Your entire WooCommerce storefront connects directly to a specific ClickUp Workspace (Team).

WooCommerce Objects ➔ ClickUp Lists

WooCommerce resources (Orders, Customers, Drafts, Abandoned Checkouts) map to distinct Lists inside your ClickUp Space.

WooCommerce Properties ➔ ClickUp Columns

Detailed attributes (e.g. order price, customer phone, tracking codes) sync into ClickUp Custom Fields/Columns.

WooCommerce Actions ➔ ClickUp Statuses

ClickUp Task Statuses (e.g. Completed) trigger bi-directional actions in WooCommerce like modifying or completing the order status.

WooCommerce Rules ➔ Tags & Priority

Conditions (like high cart value or express shipping title) auto-apply task Priorities and visual Tags.

Setup Instructions

Authentication & Connection

To begin syncing, ClickSync requires access permissions to both WooCommerce and ClickUp:

Install ClickSync: Upload and activate the ClickSync plugin zip on your WordPress site. This prepares the client securely.
Authorize ClickUp: Inside the ClickSync dashboard under settings, click "Connect ClickUp". You will be redirected to ClickUp's secure OAuth consent portal.
Grant Permissions: Log into ClickUp, choose the specific workspaces (teams) you want to grant ClickSync access to, and click **Authorize**. You will be returned to your WordPress settings dashboard.

Setting Trigger Rules

ClickSync lets you decide exactly what WooCommerce events create tasks. Under active sync channels, locate the event cards:

WooCommerce Order Created: Creates a task card when a customer pays for an order.
WooCommerce Customer Created: Creates a task card representing a new customer registration.
Order Notes & Refunds: Syncs local store logs and tracks refund transactions.
Map List Target: For each active card, select a target ClickUp **Space**, **Folder**, and **List** from the dropdown options. ClickSync automatically retrieves your ClickUp lists in real-time.

Mapping Custom Fields

Organize details directly inside ClickUp columns. First, create your columns (text, currency, date, dropdown) inside ClickUp, then map them in ClickSync:

Under **Custom Field Mappings**, choose a preset WooCommerce variable (e.g. order total, customer notes, discount codes).
Select the target ClickUp column from the dropdown.
For custom metadata, choose **Custom Path** and type the JSON path (e.g., customer.phone).
Click **Add Mapping**. Future events will populate these columns automatically.

Routing Rules & Priorities

Ensure critical events go to the right place and get assigned to the proper personnel automatically:

Assignee Routing: Navigate to routing settings, select a property (e.g., total_price), choose an operator comparison (e.g. >=), enter a threshold (e.g., 100), and select the ClickUp team member. ClickSync auto-assigns the task!
Task Priority Rules: Flag tasks as Urgent, High, Normal, or Low based on parameters like cart totals, express shipping method matches, or VIP buyer tiers.
Split Order Routing: Enable split routing on order cards to automatically break multi-item orders into linked child subtasks under a parent card.

Bi-Directional Status Sync

Let your operations team manage WooCommerce directly from ClickUp. Map a ClickUp card status to trigger order status transitions inside WooCommerce:

Locate the **ClickUp Status to WooCommerce Actions** card.
Ensure ClickSync's webhook payload URL is registered inside your ClickUp Space.
Add a mapping: Select a ClickUp status (e.g. complete) and map it to a WooCommerce action (e.g., Complete WooCommerce Order).
When a card status updates in ClickUp, ClickSync automatically executes the corresponding status transition in WooCommerce.

Checking Audit Trails & Logs

Validate your synchronization pipelines and track historical executions in real-time:

Navigate to the **Sync Audit Logs** tab in your ClickSync console.
Every webhook receipt, queue job, and API sync attempt is logged here.
View details like the trigger timestamp, event status (Success or Failed), request payloads, and click direct links to open generated ClickUp cards.
Pruned automatically after 7 days to preserve storage.

Developer API: WordPress Hooks & Filters

ClickSync is built with developers in mind. Intercept events, bypass syncing for custom conditions, modify payload data before dispatch, or customize queue limits using native WordPress action and filter hooks.

1. Selective Synchronization Filters

Bypass syncing for specific records. For example, to prevent syncing test orders or orders under a certain dollar value:

add_filter( 'clicksync_should_sync_order', function( $should_sync, $order_id ) {
    $order = wc_get_order( $order_id );
    
    // Do not sync orders under $10
    if ( $order && $order->get_total() < 10.00 ) {
        return false;
    }
    
    return $should_sync;
}, 10, 2 );

2. Outgoing Data Payload Interceptors

Append custom ACF fields or order metadata (e.g., custom delivery dates) into the sync package:

add_filter( 'clicksync_order_payload', function( $payload, $order_id ) {
    // Read a custom field from order metadata
    $delivery_date = get_post_meta( $order_id, '_custom_delivery_date', true );
    
    if ( ! empty( $delivery_date ) ) {
        // Add it to the metadata payload mapping
        $payload['metadata']['custom_delivery_date'] = $delivery_date;
    }
    
    return $payload;
}, 10, 2 );

3. Queue & Transport Customization

Override default request properties, HTTP headers, or retry parameters for complex server topologies:

// Set custom queue retry attempt limit
add_filter( 'clicksync_retry_limit', function( $limit ) {
    return 5; // Default is 3
} );

// Append custom headers for API validation
add_filter( 'clicksync_api_request_headers', function( $headers ) {
    $headers['X-Custom-Server-ID'] = 'prod-west-01';
    return $headers;
} );

4. Post-Sync Action Listeners

Trigger secondary logic inside your WordPress site when ClickSync dispatches webhook payloads:

add_action( 'clicksync_event_failed', function( $event_type, $error_message, $payload ) {
    // Log error to a custom slack channel or local admin report
    error_log( "ClickSync event {$event_type} failed: {$error_message}" );
}, 10, 3 );

Development Partnership with Loopstates

For custom integrations, enterprise solutions, or dedicated engineering support, partner with our product engineers to design, build, and deploy specialized software solutions tailored to your business operations.