Every WooCommerce order that reaches Qoblex has to be attached to a customer contact. Qoblex works out which contact that is at the moment it processes the order: it looks for an existing customer that matches, reuses it if it finds one, and creates a new one if it does not. There is no customer import and no customer list to sync. Your WooCommerce shoppers arrive in Qoblex as a by-product of their orders.
This article explains exactly how that matching works, which WooCommerce field lands in which Qoblex field, how a signed-in shopper is handled differently from a guest, and, most importantly, why the same real-world customer can end up with more than one contact record in Qoblex. After reading it you will be able to look at a duplicated contact and say which rule produced it, and decide what to change in WooCommerce so it stops happening.
When customer sync runs, and which way it flows
Customer sync is one-directional: WooCommerce to Qoblex, and it is driven entirely by orders.
- Qoblex does not subscribe to customer changes in WooCommerce. Creating, editing, or deleting a customer account in WooCommerce does nothing in Qoblex on its own. The only things Qoblex asks your store to notify it about are orders and products.
- A contact is created or updated only while Qoblex is processing a WooCommerce order. Three things bring orders in, and all three create contacts in exactly the same way: 1. An order is placed, edited, trashed, or restored in WooCommerce, and your store notifies Qoblex. 2. The background check that runs every five minutes and picks up anything modified in your store in the last few minutes, whether or not the store notifications are working. 3. A manual historical order import for a date range you choose.
- Changes you make to a contact in Qoblex are never pushed back to WooCommerce. Qoblex only ever reads customers from your store; it never writes one.
- Because the contact is worked out before the order itself is created, this happens on every order event, including cancelled and trashed orders. An order that ends up cancelled in Qoblex still leaves a contact behind.
There is no automatic first fill of past customers when you connect a store. The five-minute check only sees orders that have been modified since you connected, so the customers behind your older orders will not appear until you run a historical order import covering them.
Which path an order takes: account or guest
Before anything else, Qoblex checks one thing: does the WooCommerce order carry a registered customer account?
- Yes — the order was placed by someone signed in to an account on your store. Qoblex fetches that customer record from WooCommerce and builds the contact from it.
- No — the order is a guest order. Qoblex builds the contact from the order’s own billing and shipping details instead.
That is the only branch there is. Both paths produce an ordinary customer contact and both are matched in exactly the same way.
How Qoblex finds or creates the contact
Step 1. Qoblex works out the person, the email, and the company
On an account order, from the WooCommerce customer record:
- The person is the customer’s first name and last name, joined with a space. If both are blank, the company name from their billing address is used instead.
- The email is the customer’s account email address.
- The company is the company on their billing address. If that is blank, the person’s name is used instead.
On a guest order, from the order itself:
- The person is the billing first and last name. If those are blank, the shipping first and last name. If those are blank too, the literal words Anonymous customer.
- The email is the billing email. If the order has no billing email, Qoblex uses the fixed placeholder address
anonymous_customer@noemail.comso the contact can still be saved. - The company is the shipping company. If that is blank, the billing company. If both are blank, the person’s name is used.
Step 2. Qoblex looks for an existing customer
Qoblex searches your customers for one where both the email and the Primary Person name match what it worked out in step 1. Suppliers are never matched, only customer contacts. Qoblex tidies the name it builds from WooCommerce, trimming the ends and collapsing runs of spaces, then tries both the tidied and the untidied version against the Primary Person name on your contacts. So a stray double space in what WooCommerce sends will not split a contact. Any other difference will: a different spelling, an added initial, a hyphen.
- A match is found. Qoblex reuses that contact and attaches the order to it. Any address on this order that the contact does not already hold is added to it, and the contact’s Company name, Mobile, and Land line Phone are rewritten from WooCommerce.
- No match is found. Qoblex creates a new customer.
Step 3. What a brand-new contact looks like
A contact Qoblex creates from a WooCommerce order is always of type Customer — a WooCommerce order can never create a supplier. It carries the company, person, email, and phone numbers from step 1, and both the billing and the shipping address.
Field mapping
The contact record
| Qoblex field | WooCommerce source | Written on later orders? |
|---|---|---|
| Company name | Account order: the customer’s billing company, else their name. Guest order: the order’s shipping company, else its billing company, else the person’s name | Yes, every time. Whatever is there is replaced. |
| Primary Person name | Account order: the customer’s first + last name, else their billing company. Guest order: the order’s billing names, else its shipping names, else Anonymous customer |
Yes, but it had to match for the contact to be reused, so the value does not meaningfully change. |
Account order: the customer’s account email. Guest order: the order’s billing email, else anonymous_customer@noemail.com |
No. It is half of the match, so it is always already equal. | |
| Mobile | Account order: the customer’s billing phone, falling back to the order’s billing phone. Guest order: the order’s billing phone | Yes, whenever WooCommerce supplies one. |
| Land line Phone | Account order: the customer’s shipping phone, falling back to the order’s shipping phone. Guest order: the order’s shipping phone | Yes, whenever WooCommerce supplies one. |
| Addresses | Account order: the customer record’s billing and shipping addresses. Guest order: the order’s billing and shipping addresses | Added to. Nothing is ever replaced or removed. |
| Business type | Not supplied by WooCommerce | No. Always Wholesale, and only when the contact is created. On the Advanced tab. |
| Contact type | Always Customer | A WooCommerce order never creates a supplier. |
| Payment terms | Not supplied by WooCommerce | Never. The sync leaves the Payment terms dropdown unset; it is yours to choose. |
Price list, account manager, customer groups, sales tax, purchase tax, discount, Tax Number, and EORI are never written by this sync at all.
On an account order, only the addresses held on the customer record in WooCommerce are added to the contact. A one-off delivery address typed into a single order is recorded on that sale order but never lands on the contact.
Each address
| Qoblex address field | WooCommerce address field |
|---|---|
| Line one | address_1 |
| Line two | address_2 |
| City | city |
| State | state |
| Zip code | postcode |
| Country | country |
| Mobile | phone |
| Landline | Never written |
The Landline box on an address created by this sync is always empty. The one phone number WooCommerce holds on an address is written to the address Mobile field only.
Two addresses count as the same address when their Line one, Line two, City, Country, Zip code, and State all match. The phone number is not compared, so an address that is identical apart from its phone number is not added and the phone number already on file stays.
What Qoblex does automatically
- Creates a customer contact the first time an order arrives that does not match one you already have.
- Reuses the matching contact on every later order, so repeat buyers do not pile up.
- Adds new addresses from each order to the contact, keeping older addresses in place.
- Uses the placeholder email
anonymous_customer@noemail.comwhen a guest order carries no billing email, so the order is never blocked for the want of an address. - Falls back to the name Anonymous customer when a guest order carries no names at all.
- Sets Business type to Wholesale on every contact it creates.
- Re-checks the customer every five minutes for any order that has been touched in WooCommerce, whether or not your store notifications are working.
Why you are seeing duplicate contacts
Qoblex only reuses a contact when both the email and the person’s name match exactly. Because both are worked out again from every single order, anything that changes either one produces a contact that no longer matches the one you already have, and a new one is created. These are the causes, in roughly the order we see them.
The shopper changed their name in WooCommerce
This is the most common cause on WooCommerce, and the one that surprises people who have used other integrations.
The Primary Person name is half of the match. A shopper who marries and changes their surname, corrects a typo in their first name, or has a name tidied up by your staff in WooCommerce gets a brand-new Qoblex contact on their next order. Their earlier orders stay attached to the old contact.
The Company name is not part of the match, so changing a company name in WooCommerce does not cause this. It simply overwrites the company name on the contact you already have.
The shopper changed their email in WooCommerce
Someone edited the Primary Person name or the Email of the contact in Qoblex
The same break, from the other direction. If you tidy up a WooCommerce-fed contact — correcting a spelling in Primary Person name, or pointing Email at the accounts address — the next order from that shopper no longer matches it, and a fresh contact appears under the original name and email.
Editing the Company name is the one safe edit of the three, though it is pointless: the next order overwrites it from WooCommerce.
The same person bought once as a guest and once signed in
Two people at the same company order separately
Two buyers at the same company, each with their own email, each with Acme Fabrics in their billing company, produce two separate contacts both named Acme Fabrics, one per person.
This is how the sync is built: the company name is only a label, never the identity. There is no way to fold the two buyers into one company contact, because WooCommerce gives Qoblex nothing to tell it that they belong together.
Several contacts share the email anonymous_customer@noemail.com
Every guest order that arrives without a billing email is given the same placeholder address. Their names still differ, so each distinct name produces its own contact, and your customer list fills with different people all carrying the same odd email.
The reverse also happens: two different guests with the same name and no email collapse into a single contact, and their orders are mixed together.
The fix is in WooCommerce: make the billing email a required field at checkout.
Editing an old order in WooCommerce left a contact with no orders
Qoblex works the customer out again from scratch every time an order changes, not only when it first arrives. So editing an order you synced months ago — even a change with nothing to do with the customer, such as a note or a quantity — re-runs the whole match. The five-minute background check does the same for any order touched in your store.
If the shopper’s name or email has changed in WooCommerce since that order was placed, the re-run creates a new contact but leaves the order attached to the old one. The result is a contact with no orders against it and nothing on your activity feed to explain it. These build up quietly over time. Be careful which one you delete: the empty contact is the one built from the shopper’s current WooCommerce name and email, so it is the record every future order from them will land on. It is the one to keep.
You created the contact yourself before the first order arrived
Acme Fabrics with office@acme.com and then taking an order from buyer@acme.com under a personal name gives you a second contact, because both halves have to match.You deleted the duplicate and orders keep going to it
Deleting a contact in Qoblex is a soft delete: the record stays on file so existing orders still point at it. The WooCommerce match does not skip deleted contacts, so the next matching order attaches to the deleted contact and does not bring it back. The contact stays out of your Customers list while orders continue to pile onto it, invisibly.
If orders are going missing from a customer you deleted, this is why. Fix the cause in WooCommerce first, then decide which contact you want to keep.
Once you have duplicates, you cannot tell which one an order will land on
How to stop it happening
There is no merge action for contacts in Qoblex today, so the work is in preventing new duplicates rather than joining up the ones you have.
- Keep the shopper’s name and email stable in WooCommerce. Those two fields are the identity. Correcting a spelling in a customer’s first or last name costs you a duplicate contact, so weigh it up before you tidy.
- Make the billing email required at checkout. It stops unrelated guests collecting on the
anonymous_customer@noemail.comcontact and stops two same-named guests being merged into one. - Do not edit Primary Person name or Email on a WooCommerce-fed contact in Qoblex. Changing either makes the next order from that shopper create a duplicate, and there is no way to merge the two back together. Company name is safe to edit but not worth editing, because the next order overwrites it.
- Do not keep your own details in Company name, Mobile, or Land line Phone. All three are rewritten from WooCommerce on every matching order. Payment terms, price list, account manager, groups, tax class, discount, Tax Number, and EORI are yours: the sync never writes them.
- Expect to fix Business type yourself. Every contact this sync creates starts as Wholesale, including on a purely consumer store where Retail is correct. The sync sets it once, when it creates the contact, and never touches it again, so your correction sticks.
- Do not correct an address on the contact either. Addresses are re-derived from WooCommerce on every order. Editing one in Qoblex adds a second address rather than correcting the first, and deleting one only sticks if WooCommerce has stopped sending it. Correct the address in WooCommerce.
- Clean up existing duplicates last, and from the WooCommerce side first. Until the store data stops producing two names, you will keep getting new ones — and deleting the wrong one hides it from your list without stopping orders from landing on it.
Troubleshooting
A WooCommerce customer has not appeared in Contacts at all
Contacts arrive only with orders, so a shopper who has never placed an order that reached Qoblex will not be in your contacts list.
On a newly connected store, the usual cause is that nothing has pulled their order across yet. Qoblex does not import your past orders automatically when you connect; the five-minute background check only picks up orders that have been modified in WooCommerce since you connected. Run a historical order import for a date range that covers them.
Otherwise check that the order itself synced. See How WooCommerce order sync and order editing work for the conditions an order has to meet.
Every WooCommerce contact says Wholesale
That is expected. WooCommerce sends nothing Qoblex can use to tell a consumer from a business, so every contact this sync creates is given the Wholesale business type.
Change it on the contact’s Advanced tab. The sync sets Business type only when it creates the contact and never changes it afterwards, so your correction sticks.
A contact has the email anonymous_customer@noemail.com
That contact came from one or more guest orders with no billing email on them. Qoblex uses this one fixed placeholder so the contact can still be saved.
Every guest order without a billing email shares the same placeholder address, so different shoppers with the same name end up on the same contact and their orders are mixed together. Make the billing email required at your WooCommerce checkout to stop it growing, and check the orders already on the contact before you rely on it.
A new contact has the same address twice
Expected on a newly created contact. WooCommerce always sends a billing address and a shipping address, and for most shoppers the two are identical. The duplicate check only runs when an existing contact is updated, so the two rows both land when the contact is first created.
Delete the spare row if you want to. It will not come back, because the check does run from then on.
The Landline box is empty on a WooCommerce address
A contact has nobody on its Contacts tab
A contact has no orders against it
Almost always the result of an order being edited in WooCommerce after the shopper’s name or email changed there. Qoblex works the customer out again on every order event, creates the contact that now matches, and leaves the order where it was. See Editing an old order in WooCommerce left a contact with no orders above.
Do not delete the empty contact by reflex. It was built from the shopper’s current WooCommerce details, so it is the one their next order will match. Delete the older contact only if you are sure it no longer matches what WooCommerce holds, and move on rather than deleting either if you are unsure.
The contact’s old address is still there after the customer moved
Addresses are added, not replaced. The sync never removes an address a contact already holds, so historical orders keep their addresses.
Deleting the stale one in Qoblex only sticks if WooCommerce has stopped sending it. If it is still on the customer record, or still on an order that syncs, the next order adds it straight back. Change it in WooCommerce first.
One order never arrives and nothing appears on the activity feed
Check the customer account on that order in WooCommerce. A registered customer with no first name, no last name, and no company on their billing address leaves Qoblex with nothing to name the contact after, and a contact cannot be saved without a name. The order is retried rather than reported, so it never appears and no message is written to your activity feed.
Fill in a name or a billing company on that WooCommerce customer, then edit the order in WooCommerce so it is picked up again.
There is a second cause with exactly the same symptom. If the WooCommerce account the order points at has been deleted — a removed user, or personal data erased on request — Qoblex cannot read the customer and the order retries silently in the same way, with nothing on the activity feed. In that case there is no customer left to correct, so open the order in WooCommerce and set its customer to one that still exists, or to Guest, then save. As a guest order it syncs from the billing details on the order itself.