Order Sync & Troubleshooting

Every time a customer completes a purchase, Tracksies grabs the order details and builds (or updates) that customer’s profile — tracking lifetime value, order count, average order value, tags, and more. It’s like a live scorecard that updates as the game plays out.

—

What This Is

Order Sync is the connection between your WooCommerce orders and Tracksies customer profiles. When an order comes through, the sync engine:

• Creates or updates the customer’s profile in Tracksies HQ
• Records the transaction (order total, items, payment method, coupons — everything)
• Recalculates lifetime value, order count, and average order value
• Triggers tag recalculation so achievements stay current

You don’t need to press a button or remember to “refresh” anything. The sync engine watches your orders and does the maths in the background, so your customer intelligence is always current.

—

Why It Matters

A customer profile is only useful if it reflects reality. If someone places three orders today and their profile still shows yesterday’s data, you’re making decisions based on stale information.

Without Order Sync:

• Customer lifetime values would be out of date
• Tags wouldn’t update when customers hit new milestones
• Your VIP customers might not be recognised until you manually checked
• Reports would show incomplete data

Order Sync makes sure none of that happens. Every qualifying order event triggers a recalculation — tags update, statuses shift, lifetime value climbs. It all happens automatically, like a spreadsheet that recalculates when you change a cell.

—

Before You Start

• Tracksies HQ must be installed and active on your WordPress site
• WooCommerce must be active — Order Sync connects directly to WooCommerce’s order system
• The woo.order_sync feature must be enabled — check this at Tracksies > Settings > Features (it’s on by default, but worth confirming if things aren’t syncing)

—

How Sync Works

The sync engine runs automatically in the background. Here’s the full flow of what happens when a customer places an order:

1. The order status changes to “Processing” or “Completed” — this is what kicks things off. It also fires when a payment complete webhook arrives.

1. Tracksies checks if this order has already been synced — the system is idempotent, which means it won’t create duplicate records if the same order triggers twice. This is a safety net so you never end up with inflated numbers.

1. The billing email is validated — every customer profile in Tracksies is anchored to an email address. If the order doesn’t have a billing email (rare, but it happens with some custom checkout setups), the sync stops here and logs an error so you can fix it.

1. Tracksies finds or creates the customer profile — if this email already has a profile, the existing one is updated. If it’s a brand new customer, a fresh profile is created. The profile pulls in their first name, last name, phone number, company name, and WordPress user ID (if they have an account).

1. The transaction is recorded in Tracksies HQ — this captures the full picture of the order: order ID, order number, total, any discounts applied, payment method, shipping method, item count, and coupons used. The transaction is tagged with a “woocommerce” channel and marked as “completed.”

1. Order meta is updated — Tracksies stores a few pieces of data on the WooCommerce order itself (more on this below), including a timestamp of when the sync happened and the linked customer ID.

1. The tracksies_customer_synced hook fires — this triggers tag recalculation, so if this order pushes the customer past a tag threshold, they earn it right away.

—

What Gets Synced

Customer Data

Transaction Data

Calculated Metrics

These are recalculated every time a new transaction syncs:

—

Order Meta

Tracksies stores a few meta values directly on each WooCommerce order. This is how it tracks sync status without needing a separate database table:

You’ll see this information reflected in the sync status indicators on your order screens (more on that in the next section).

—

Checking Sync Status

On the Orders List

When any orders have failed to sync, you’ll see an admin notice at the top of the WooCommerce > Orders page showing the count of failed syncs. Think of it like a “check engine” light — it’s there so you can address it, not panic about it.

The notice includes a Retry All button that lets you re-process all failed syncs in one go.

On Individual Orders

You can check the sync status of any specific order:

1. Go to WooCommerce > Orders and click on the order you want to check
2. Look for the Tracksies sync status in the order meta box — you’ll see one of three states:

– Synced (with a timestamp) — everything worked. You’ll also see a View Customer link that takes you straight to that customer’s Tracksies profile.
– Failed (with an error reason) — something went wrong. A Retry button lets you try syncing this order again.
– Pending — the order hasn’t been synced yet. A Sync Now button lets you trigger it manually.

The status indicators are colour-coded so you can spot issues at a glance.

—

Importing Existing Orders

When you first activate Tracksies HQ, you’ll probably have existing WooCommerce orders that need to be pulled in. The Import Orders feature handles this.

What it does:

• Runs a one-time bulk sync of all your existing WooCommerce orders
• Builds complete customer profiles with accurate lifetime values and tag data
• Runs in the background so it doesn’t slow down your site for shoppers

What to expect:

• A store with around 500 orders will finish in under a minute
• If you have 10,000+ orders, expect it to take 5-10 minutes
• You can keep using your site normally while it works
• You’ll see profiles appear in Tracksies > Customers as syncing progresses — they don’t all appear at once

This feature uses the woo.import feature flag. It’s designed as a one-time operation, so once it’s done, ongoing syncs are handled automatically by the regular sync engine.

—

Common Questions

Does sync slow down my site?
No. The sync happens in the background using WordPress cron (a scheduling system built into WordPress). Your customers won’t notice a thing during checkout or browsing.

What if I add orders manually?
Manual orders sync the same way as customer-placed orders. When the order status moves to Processing or Completed, the sync picks it up.

Are refunded orders counted in lifetime value?
No. Only orders that have reached Processing or Completed status count toward LTV. Refunded orders are excluded from the calculation.

What about guest orders where the customer didn’t create an account?
Guest orders are matched by billing email address. If the same email appears across multiple guest orders, they all roll up into one customer profile. This means your LTV numbers are accurate even for customers who never create an account.

Can the same order sync twice and inflate the numbers?
No. The sync engine is idempotent — it checks the _tracksies_synced meta on each order before processing. If an order has already been synced, it’s skipped. This protects against duplicate data from webhook retries or status change loops.

What triggers a sync?
Three things: an order status changing to “Processing” or “Completed,” a payment complete webhook firing, or you manually clicking Retry or Sync Now on an order.

—

Troubleshooting

Customer profiles are empty
The initial import may still be running. Give it a few minutes, then refresh the page at Tracksies > Customers. Profiles appear as they’re processed — not all at once. If they’re still empty after 10 minutes, check that the woo.order_sync feature is enabled at Tracksies > Settings > Features.

Lifetime value shows $0
Check that the customer’s orders have a “Completed” or “Processing” status in WooCommerce > Orders. Orders that are still on hold, pending, or cancelled aren’t counted toward LTV. Once an order moves to a qualifying status, the value updates automatically.

The “failed sync” notice won’t go away
Click the Retry All button on the admin notice at the top of the WooCommerce > Orders page. If syncs keep failing after retrying, check the error reason on individual orders — click into the order and look at the Tracksies sync status in the meta box. The error code will tell you what went wrong.

Error: no_billing_email
The order doesn’t have a billing email address, and Tracksies needs one to create or match a customer profile. This usually happens with orders created programmatically or through a custom checkout flow. Edit the order in WooCommerce > Orders, add the billing email, and click Retry in the sync status box.

Error: order_not_found
The order was deleted or moved to the trash between when the sync was scheduled and when it ran. This isn’t something you need to fix — the order no longer exists, so there’s nothing to sync.

Error: customer_creation_failed
Something went wrong when Tracksies tried to create the customer profile. This could be a temporary database issue. Click Retry on the order to try again. If it keeps failing, check your site’s error logs — there may be a database connection issue or a plugin conflict.

A customer is missing from the list
They may not have any qualifying orders yet — customers only appear once they have at least one order that’s reached Processing or Completed status. It’s also worth checking whether their order failed during sync by viewing it in WooCommerce > Orders and looking at the sync status in the meta box.

Sync seems stuck
Check whether your WordPress cron is running. Some hosting providers disable the built-in wp-cron system and require you to set up a real server cron job instead. If you’re not sure whether this applies to you, your hosting provider can confirm — it’s a quick question for their support team.

Tags aren’t updating after new orders
Tag recalculation is triggered by the tracksies_customer_synced hook, which fires at the end of a successful sync. If the order hasn’t synced yet (check for the _tracksies_synced timestamp on the order), tags won’t update until it does. If the order shows as synced but tags still haven’t changed, the customer may not have reached the threshold yet — check the tag rules at Tracksies > Settings.

—

Importing Existing Orders (Initial Setup)

When you first install Tracksies HQ, your store likely already has WooCommerce orders and customers. The Import feature (hq.import, enabled by default) lets you pull all that existing history into Tracksies in one go, so your customer profiles start with accurate lifetime values, order counts, and tags from day one.

How to Run the Import

1. Go to Tracksies > Settings
2. Look for the Import section
3. Click the import button to start the bulk sync

The import runs in the background, so your site stays responsive for shoppers while it works. A store with around 500 orders will typically finish in under a minute. Larger stores with 10,000+ orders may take 5-10 minutes.

What It Does

• Processes all existing WooCommerce orders (completed and processing)
• Creates or updates customer profiles with accurate data
• Calculates lifetime values, order counts, and average order values
• Triggers tag calculation so customers start with the correct tags

When to Use It

This is a one-time operation designed for initial setup. Once the import is done, the regular Order Sync engine handles all new orders automatically. You don’t need to run the import again unless you’ve reinstalled Tracksies HQ from scratch and need to rebuild customer data.

Customer profiles appear in Tracksies > Customers as syncing progresses — they don’t all show up at once, so give it a few minutes before checking.

—

Auto-Complete for Digital Orders

If you sell digital or downloadable products, you may not need those orders to go through the full packing and shipping workflow. The hq.digital_auto_complete feature (off by default) automatically marks orders as Complete when they contain only digital/downloadable products.

Enabling Auto-Complete

1. Go to Tracksies > Settings in the left sidebar
2. Click the Features tab
3. Find the HQ module tile
4. Look for Digital Auto-Complete and switch it on

How It Works

When an order is placed and all items in the order are digital or downloadable (no physical products), Tracksies skips the Processing/Packed/Shipped workflow and moves the order straight to Completed. The customer gets their download links immediately, and the order doesn’t clog up your packing queue.

If an order contains a mix of physical and digital products, it goes through the normal fulfilment workflow. Auto-complete only kicks in when every item in the order is digital.

When to Use It

This is most useful for stores that sell a combination of physical and digital products. If your packing team is wading through digital orders in the packing queue that don’t need any action, turning this on clears the clutter and lets them focus on orders that actually need to be shipped.