Skip to main content

Tracking Sync

Synchronize shipping tracking numbers from Microsoft Dynamics 365 Business Central to your BigCommerce and WooCommerce stores.

Overview​

Tracking Sync automatically:

  • Fetches tracking numbers from Business Central shipments
  • Posts tracking to your e-commerce platform
  • Updates order status (optional)
  • Sends customer notification emails (optional)
  • Handles partial shipments and cancellations

Schedule: Every 30 minutes
Execution: 2-5 minutes per site

How It Works​

Sync Flow​

  1. Cron Schedule: Runs every 30 minutes automatically
  2. Fetch Orders: Gets orders with specific status codes from your platform
  3. Query Business Central: Retrieves tracking data via OData API
  4. Validate: Filters excluded carriers and validates tracking numbers
  5. Post to CMS: Creates shipment records in BigCommerce/WooCommerce
  6. Update Status: Marks orders as completed (if configured)
  7. Health Check: Pings monitoring URL on success

Status Filters​

Status filters determine which orders are checked for tracking updates:

Default: 9,3

  • Status 9: Awaiting Shipment (no tracking yet)
  • Status 3: Partially Shipped (some items shipped)

You can customize this comma-delimited list per site in the Control Panel.

Configuration​

Navigate to GSM Middleware → Control Panel and edit your site.

Tracking Sync Tab​

Enable Tracking Sync​

Toggle to enable/disable tracking synchronization for this site.

Health Check URL​

Optional URL to ping after successful sync (e.g., https://healthchecks.io/ping/your-id).

Useful for monitoring via healthchecks.io, Better Uptime, UptimeRobot, or custom tools.

Status Filters​

Comma-delimited order status codes to sync.

Default: 9,3
Examples: 9 (awaiting only), 3 (partial only), 9,3 (both - recommended)

Auto-Complete Orders​

When enabled, orders are automatically marked as "Completed" when tracking is posted.

Default: Enabled (opt-in)

Disable if you manually review shipments or have custom workflows.

Send Customer Email​

When enabled, triggers the platform's shipment notification email.

Default: Enabled (opt-in)

Carrier Mapping​

Business Central carrier codes are automatically mapped to platform-specific codes via the rm_carrier_mapping table.

Default Mappings​

Business CentralBigCommerceWooCommerce
FEDEXfedexfedex
UPSupsups
USPSuspsusps
DHLdhldhl
CANADAPOcanada-postcanada-post

Custom Mappings​

Add custom carrier mappings via SQL:

INSERT INTO rm_carrier_mapping (platform, bc_carrier_code, platform_carrier_code)
VALUES ('bigcommerce', 'DHL-EXPRESS', 'dhl');

Excluded Carriers​

  • CPU - Customer Pickup (no tracking number needed)

Manual Trigger​

Manually trigger tracking sync for a specific site:

  1. Go to GSM Middleware → Control Panel
  2. Find the site in the list
  3. Click the "Tracking" button (location icon)
  4. Wait for confirmation message

This queues a background job that processes immediately.

Platform Differences​

BigCommerce​

Shipment Creation:

  • Uses /orders/{id}/shipments API endpoint
  • Auto-matches line items by SKU
  • Supports multiple shipments per order
  • Includes tracking_carrier if mapped

Order Completion:

  • Updates status_id to 10 (Completed)
  • Only when current status is 2 (Shipped)

WooCommerce​

Shipment Creation:

  • Preferred: WooCommerce Shipment Tracking plugin
  • Fallback: Customer note with tracking info

Order Completion:

  • Updates status to completed
  • Triggers WooCommerce completion hooks

Troubleshooting​

Tracking Not Appearing​

  1. Check Site Config: Verify Tracking Sync is enabled
  2. Check Status Filters: Order must match configured statuses
  3. Check Business Central: Shipment must exist with tracking number
  4. Check Carrier: Must not be in excluded list

Duplicate Tracking​

System prevents duplicates via shipments table. If duplicates occur:

  • Check middleware logs
  • Verify order number format
  • Confirm shipment records

Orders Not Completing​

  1. Check Auto-Complete: Must be enabled in settings
  2. Check Platform Status: BigCommerce must be status 2 first
  3. Check Permissions: Verify API credentials allow status updates

API Endpoints​

Trigger Sync for Site​

POST /wp-json/gsm-middleware/v1/tracking/sync/{site_id}

Trigger Sync for All Sites​

POST /wp-json/gsm-middleware/v1/tracking/sync-all

Get Sync Status​

GET /wp-json/gsm-middleware/v1/tracking/status/{site_id}

Database Tables​

  • shipments - Tracking numbers and shipment details
  • shipments_line_item - Links shipment items to order products
  • rm_carrier_mapping - Platform-specific carrier code mappings

See Database Schema for details.

Best Practices​

  1. Monitor Health Checks: Set up external monitoring
  2. Test Status Filters: Start with default 9,3
  3. Review Auto-Complete: Disable for custom workflows
  4. Check Carrier Mappings: Add as needed
  5. Use Manual Trigger: Test before full automation