TCPOS Product Sync

Synchronizes TCPOS products into WooCommerce and pushes WooCommerce orders back to TCPOS.

This plugin aims to keep products in sync from TCPOS to WooCommerce and to notify TCPOS about orders and payment status updates from your store.

Features

• Admin dashboard page: TCPOs Sync
• Settings stored in wp_options
• Manual sync actions (Test Connection / Run Full Sync / Sync Updates)
• AJAX settings form save (no page reload)
• AJAX admin notices for save/sync/test actions
• Automatic product sync via WP-Cron (tcpos_sync_products_event, every 5 minutes)
• Product upsert by _tcpos_id with category auto-create and stock management
• Immediate outbound order sync when an order is created via checkout (hook: woocommerce_checkout_order_created)
• Non-blocking frontend AJAX hook that attempts to sync when the customer completes checkout (sends order_id to admin AJAX endpoint)
• Separate order-status-update endpoint to report payment status/type/amount
• Option to send a dummy paid amount (random value <= order total) for testing/privacy
• Skips sending payment updates for unsupported payment methods (cash/COD, cheque) or when no payment method is available
• Duplicate guard using order meta _tcpos_synced to avoid re-creating the same order in TCPOS
• Logging to logs/plugin.log + recent logs in wp_options
• API retry behavior for transient failures (timeouts, 5xx, 429)

Key Paths

• tcpos-product-sync.php - plugin bootstrap
• api/ApiClient.php - API client + retry + pagination helpers
• sync/ProductSyncService.php - product import/update service
• sync/OrderSyncService.php - completed order sync service
• sync/class-sync-manager.php - cron hooks + orchestration
• admin/class-admin.php - settings, UI, AJAX handlers
• logs/class-logger.php - file/option logging utilities

New / changed files of interest:

• admin/js/tcpos-checkout.js - frontend JS that attempts a non-blocking AJAX POST to the plugin when checkout completes
• api/ApiClient.php - added updateOrderPaymentStatus() and configuration for an "order status update" endpoint
• sync/OrderSyncService.php - includes order_id (as string) in the creation payload and handles sending payment status updates (amount, payment_type, payment_status)
• admin/class-admin.php - settings UI now includes Order Status Update Endpoint and Use Dummy Paid Amount options

Setup

1. Activate plugin in WordPress admin.
2. Open TCPOs Sync menu.
3. Configure:
   • API Base URL
   • Products Endpoint
   • Orders Endpoint
   • Order Status Update Endpoint (optional) — POSTs payment updates: order_id (string), payment_status, payment_type, status, amount
   • API Key (optional)
   • Store/Organisation ID (optional)
   • Use Dummy Paid Amount (Yes/No) — if enabled the plugin will send a random amount less than or equal to the order total when reporting payment updates (useful for testing)
4. Save settings.
5. Use Test Connection before first full sync.

Where To Find It In Dashboard

• Left admin menu: TCPOs Sync
• WordPress Dashboard widget: TCPOs Sync Status

The dashboard widget shows the last sync summary and a quick button to open plugin settings.

AJAX Behavior

• The settings form is submitted using AJAX and saved to wp_options.
• Sync buttons send current form values via AJAX before running actions.
• Results are shown in-page and also rendered as WordPress admin notices via AJAX.
• Only the API Base URL is required for sync operations. API Key and Store/Organisation ID are optional.

Frontend checkout behavior

• When a customer completes checkout, the plugin's frontend script (admin/js/tcpos-checkout.js) attempts a non-blocking AJAX POST to the plugin's tcpos_product_sync_checkout_order_sync action with order_id.
• This is best-effort and non-blocking — it will not delay checkout. The server-side handler will call the existing order sync logic (and/or payment update logic) for the provided order.
• The plugin also hooks into WooCommerce order status changes (status-created and status-changed) and will call the configured Order Status Update Endpoint when appropriate.

Sync Mapping

• id -> _tcpos_id
• attributes.name -> product title
• attributes.notes -> product description
• attributes.product_price -> WooCommerce price (_price)
• attributes.stock.quantity or attributes.in_stock -> _stock
• attributes.product_category_name -> WooCommerce product_cat

Order Payload

When an order reaches completed, this payload is sent:

{
  "order_id": "123",
  "products": [{ "product_id": "abc", "quantity": 1 }],
  "total": 1000,
  "customer": { "name": "Jane Doe", "email": "jane@example.com" }
}

Testing

• Validation checklist: tests/validation-checklist.md
• Smoke test script: tests/smoke-test.php

Order status update payload

When reporting a payment/status update the plugin will POST to the configured Order Status Update Endpoint with a payload similar to:

{
  "order_id": "123",
  "payment_status": 1,
  "payment_type": 2,
  "status": 2,
  "amount": 25.50
}

Validation & skip rules

• The plugin will not send payment updates when the order's payment method is missing.
• The plugin will skip updates for cash/COD and cheque methods (these are not sent by default).
• The plugin validates that payment_type, payment_status and status are within supported ranges before attempting to POST. If invalid, the request will be aborted and an error logged.

Deployment

1. Ensure plugin is configured and sync tested in staging.
2. Remove temporary/dev-only artifacts if added during local development.
3. Package plugin folder as zip.

Example packaging command:

cd /Users/idristabi/Projects/wordpress/brenssmallchops/wp-content/plugins
zip -r tcpos-product-sync.zip tcpos-product-sync

Troubleshooting Visibility

If the plugin does not appear in WordPress admin:

1. Confirm folder path is wp-content/plugins/tcpos-product-sync.
2. Confirm main file exists: wp-content/plugins/tcpos-product-sync/tcpos-product-sync.php.
3. In Plugins, activate TCPOS Product Sync.
4. Log out/in and hard refresh admin.
5. Check wp-content/plugins/tcpos-product-sync/logs/plugin.log for startup errors.

Logging and debugging

• The plugin logs important steps to wp-content/plugins/tcpos-product-sync/logs/plugin.log and stores recent log entries in an option for quick retrieval in the admin UI.
• Archived log files are compressed to .log.gz and kept for 7 days before removal.
• Recent log entries stored in the database are also pruned on the same 7-day window.
• If you enable the Order Status Update Endpoint, you can temporarily point it at a request inspector (e.g., https://webhook.site/) to confirm payload shape and field contents.

Notes

• order_id is always sent as a string to both the orders endpoint and the order-status-update endpoint.
• The frontend AJAX attempt is best-effort; the server-side hooks also run on order creation and status changes to ensure updates are sent even if the client-side request does not arrive.
• If you want to ensure only real payments are reported, leave "Use Dummy Paid Amount" disabled (default). Enable it only for testing.