Resolve duplicate account and contact sync errors

You see a sync error in the sync-error-tool with one of the following status codes:

  • DUPLICATES_DETECTED — the message varies by object, for example: "It looks like you are creating a duplicate Account. We recommend you use an existing Account instead." or "It looks like you are creating a duplicate Contact. We recommend you use an existing Contact instead."
  • DUPLICATE_VALUE — "A unique column has a duplicate value."
  • CANNOT_EXECUTE_FLOW_TRIGGER with an inner DUPLICATES_DETECTED message — a third-party Flow or Process is performing its own duplicate check during sync.
  • Orders failing to sync because the referenced account no longer exists in Salesforce.

These errors occur on Account, Contact, or Lead records during sync.

Cause of duplicate account and contact sync errors

StoreConnect automatically checks existing customer records during checkout to avoid creating duplicates in Salesforce. It matches customers to existing leads, contacts, and accounts using a combination of name, email, and phone fields. For full details on how this works, see lead-contact-and-account-deduplication.

Despite this, Salesforce-side duplicate rules can still block the sync. StoreConnect's duplicate resolution runs on the store side before data is sent to Salesforce, but Salesforce's own Duplicate Rules fire independently when the record is saved to Salesforce. If a Salesforce Duplicate Rule is set to Block, the sync will fail even though StoreConnect has already performed its own duplicate checks.

Alert (Prompt) mode rules also cause sync failures. When a duplicate rule is set to Alert, Salesforce shows a warning that a manual user can acknowledge and continue past. StoreConnect's sync runs automatically and cannot respond to that warning, so the sync fails in the same way it would under a Block rule. Both Block and Alert mode duplicate rules can cause sync errors for the StoreConnect Sync User.

There are three common scenarios that cause this error:

  1. Salesforce Duplicate Rules blocking sync — the org has standard or custom duplicate rules on Account or Contact set to Block, which prevents the record from being created or updated.
  2. Orphaned reference (account merged or deleted in Salesforce) — an account was merged or deleted in Salesforce, but StoreConnect still holds the old reference. When an order tries to sync against the old record, it fails because the Salesforce record no longer exists.
  3. Third-party package Flow — an installed package (e.g., a tax calculation or ERP integration package) runs a Flow that performs its own duplicate check during the sync operation.

Resolution for duplicate account and contact sync errors

Rather than adjusting duplicate rules each time a sync error occurs, configure duplicate rules to skip enforcement for the StoreConnect Sync User permanently. This resolves both Block and Alert mode failures and is the recommended long-term solution.

  1. In Salesforce, go to Setup and search for Duplicate Rules.
  2. Open the duplicate rule causing the sync failure.
  3. Under Conditions, add a condition: Current User: Profile → not equal to → Salesforce API Only System Integrations.
  4. Save and activate the rule.
  5. Re-sync affected records via the sync-error-tool.

This leaves duplicate protection fully intact for all manual users. StoreConnect already performs its own duplicate checking on the store side before records are sent to Salesforce (see lead-contact-and-account-deduplication), so excluding the Sync User from Salesforce-side rules avoids redundant enforcement without reducing data quality.

ℹ️ Note

If your org uses multiple duplicate rules on the same object, add the Sync User exclusion condition to each rule. Salesforce allows a maximum of 5 duplicate rules per object.

Scenario B: Disable the alert action

If the duplicate rule is set to Alert rather than Block, a quicker fix is to remove the alert action entirely:

  1. In Salesforce, go to Setup and search for Duplicate Rules.
  2. Open the rule causing the failure.
  3. Under the rule's actions, uncheck the Alert checkbox (apply to both Create and Edit if applicable).
  4. Save the rule.
  5. Re-sync affected records via the sync-error-tool.

The matching rule will still run and potential duplicates will still be logged for reporting — they just won't block the sync or prompt during the process. This is a minimal change that preserves duplicate visibility while unblocking the sync.

Scenario C: Temporarily deactivate the duplicate rule

If there are genuine duplicates that need to be merged, temporarily deactivate the rule to allow the sync through, then merge and re-enable:

  1. In Salesforce, go to Setup and search for Duplicate Rules.
  2. Identify the rule(s) on the Account or Contact object that are set to Block.
  3. Temporarily deactivate the blocking duplicate rule.
  4. Re-sync all affected records via the sync-error-tool.
  5. After sync completes, merge the duplicate records in Salesforce.
  6. Re-enable the duplicate rule.
ℹ️ Note

Resolve all other sync errors that reference the same account before merging. Merging while related records are still in error can cascade new failures.

💡 Tip

Select all records in the list when re-syncing, not just the one that failed. Related events for the same record may also need to be re-processed.

Scenario D: Orphaned reference (account merged or deleted)

When an account is merged or deleted in Salesforce, StoreConnect may still hold the old reference. You need to update the reference to point to the correct Salesforce record.

  1. Locate the sync error in the sync-error-tool and note the sc_id value from the error detail.
  2. Identify the correct Salesforce Account ID — this is the merge winner or the replacement record.
  3. Update the reference using one of these methods:

Via the Sync Error Panel:

Open the error detail in the Sync Error Tool, edit the changed fields to point to the correct Account SFID, then click Re-sync.

Via the Developer Console:

Query the Change Event to find the affected record:

SELECT s_c__changed_fields__c, ID
FROM s_c__Change_Event__c
WHERE s_c__object_sc_id__c = '<sc_id_value>'

Find the related order if needed:

SELECT ID FROM Order
WHERE s_c__sc_id__c = '<sc_id_value>'

Update the Change Event's changed fields to reference the correct Account SFID, then re-sync.

Scenario E: Third-party Flow triggering duplicate check

  1. Read the error message to identify the specific Flow or Process name (e.g., "Acme Tax Duplicate Check").
  2. Contact the package vendor or your Salesforce administrator to fix the Flow's entry criteria.
  3. Alternatively, temporarily disable the third-party Flow, re-sync the affected records, then re-enable it.
  4. Consider adding an entry condition to the Flow to exclude the StoreConnect Sync User — see resolve-flow-trigger-sync-errors for details on this pattern.

Best practices for duplicate management

When configuring Salesforce Duplicate Rules alongside StoreConnect, follow these recommendations:

  • Exclude the StoreConnect Sync User. On each duplicate rule, add a condition: Current User: Profile → not equal to → Salesforce API Only System Integrations. This prevents sync failures while still protecting manual data entry by your team. StoreConnect performs its own duplicate checking before records reach Salesforce, so this does not reduce data quality.
  • Use "Allow + Report" mode first. Deploy duplicate rules in report-only mode for a week, inspect logged duplicates, tune matching criteria, then switch to Block mode if needed. See Salesforce Duplicate Rules.
  • Use stable identifiers. Match on Email or External ID as the primary criteria, with fuzzy name and phone matching as a fallback.
  • Create exact-name matching rules for Accounts and Contacts. This prevents identical Account or Contact names from being created while allowing similar-but-different records through.
  • Know the limits. Salesforce allows a maximum of 5 duplicate rules per object. Standard matching rules don't cover every scenario, so you may need custom matching rules for your specific data patterns.
  • Consider client-defined matching rules for the integration user. Rather than applying generic matching rules across all users, clients can define their own duplicate and matching rules specifically for the integration profile. This lets each client align rule behaviour with their business processes — the StoreConnect Sync User can operate under a different rule set from what manual users see.
  • Review data quality periodically. Duplicate rules are not a "set and forget" solution. Schedule regular reviews. See Trailhead: Prevent Duplicate Data.

Verify sync errors

  1. Confirm the sync error no longer appears in the sync-error-tool.
  2. Open the synced record in Salesforce and verify the account association is correct.
  3. If accounts were merged, confirm that orders and contacts are now linked to the correct surviving account.

Preventing duplicate account and contact sync errors

  • Before merging accounts in Salesforce, check the sync-error-tool for pending errors that reference that account.
  • Add a Current User: Profile exclusion condition for Salesforce API Only System Integrations on all duplicate rules that apply to Account, Contact, or Lead objects.
  • When setting up the StoreConnect Sync User for a new client, configure duplicate rule exclusions as part of the initial setup — don't wait until errors occur. This is a predictable failure mode that can be prevented before any records are synced.
  • Audit duplicate rules after installing third-party packages — new Flows may introduce additional duplicate checks.
  • Review how StoreConnect handles duplicates at checkout in lead-contact-and-account-deduplication.
Last updated March 13, 2026

Related Articles

DocumentationManage sync errorsVideos & tutorials▶️ Find and resolve sync errorsDocumentationResolve Flow and trigger blocking sync errorsDocumentationAutomated lead conversion to avoid duplication