Woo-Clover Sync

A WordPress plugin that keeps a WooCommerce store in sync with a Clover POS merchant — products, inventory, and orders — so online and in-person sales share one catalog and one stock count.

What it does

• Product & catalog mapping — maps WooCommerce products to Clover items and keeps a persistent mapping table so updates flow to the right record.
• Inventory sync — reconciles stock levels between WooCommerce and Clover.
• Order sync — pushes/receives orders and reacts to Clover events.
• Webhook receiver — exposes a REST endpoint for Clover to notify the store of changes (POST /wp-json/wcs/v1/clover-webhook).
• Secure credentials — merchant ID and API keys are stored encrypted (AES via OpenSSL, key derived from WordPress salts), never in plaintext.
• Flexible auth — uses a Clover OAuth access token when available and falls back to an x-api-key API key otherwise.
• Admin UI — a "Clover Sync" settings area with a one-click Test credentials action, an overview page, and a pending-orders view.

Tech stack

WordPress / PHP · WooCommerce · Clover REST API (production hosts api.clover.com, token.clover.com, scl.clover.com)

Architecture

WooCommerce  <—>  Woo-Clover Sync (WP plugin)  <—>  Clover REST API
                        |
                        +— wp_wcs_mappings  (product/order id map)
                        +— wp_wcs_logs      (sync + webhook audit log)

• woo-clover-sync.php — entry point; loads focused classes with a legacy-path fallback.
• includes/api/ — WCS_Client (auth/token), WCS_Service (request helper), WCS_Rest (webhook route).
• includes/db/ — WCS_DB creates the mapping + log tables via dbDelta.
• includes/utils/ — WCS_Crypto (AES encrypt/decrypt of stored credentials).
• includes/setup/ — WCS_Activator (activation / table creation).
• includes/admin-pages/ — Settings, Overview, Pending Orders.
• config/clover_endpoints.yml — a catalog of Clover REST endpoints (cash, customers, employees, inventory, notifications, orders, payments, apps, print) used as an integration reference.

Requirements

• WordPress 6.x with WooCommerce active
• PHP 8.x
• A Clover developer app (OAuth) or an API key, plus your merchant ID

Quickstart

1. Copy the plugin into wp-content/plugins/woo-clover-sync/ (or deploy via CI).

2. Activate it — the activator creates the wcs_mappings and wcs_logs tables.

   wp plugin activate woo-clover-sync

3. In WP Admin → Clover Sync → Settings, enter your Clover merchant ID and credentials (OAuth token or API key). Credentials are encrypted at rest.

4. Click Test credentials to confirm connectivity.

5. Register the webhook in your Clover app pointing at https://<your-site>/wp-json/wcs/v1/clover-webhook.

Screenshots

Development

# Start a local WordPress + WooCommerce stack, then:
wp plugin activate woo-clover-sync

CI runs PHP lint, PHPCS, a secret scan, and an asset build on every change, and provisions a per-branch preview site with the plugin active.

Contributing

Branch from main, open a pull request, and let CI run. Never commit literal secrets — Clover credentials are entered in the admin UI and stored encrypted.

Status

Early-stage integration. Contributions and issue reports are welcome.