Skip to main content

Connector Operations

This guide explains how merchants and operators should reason about connector health after a provider has been configured.

Connection States​

Live​

The provider is connected and eshopOS has an active install record for the current store.

Use this state to:

  • verify the linked external domain
  • confirm granted access scope
  • begin preview or import work

Inactive​

The provider is not currently active for the store. This can mean:

  • the store has never been connected
  • the connector was disconnected
  • the setup was interrupted before completion

Failed​

The provider callback or token exchange did not complete successfully. A failed state should be treated as incomplete setup until a new configure flow succeeds.

Reconfigure vs Disconnect​

Configure and Disconnect are not the same action.

Use Configure when:

  • the store needs to connect for the first time
  • a previous connection failed
  • the merchant wants to reconnect with a fresh provider authorization

Use Disconnect when:

  • the external store should no longer be linked
  • the merchant is changing platforms
  • the operator wants to remove provider access intentionally

What Merchants Should Check After Connecting​

After the provider returns to eshopOS, the merchant should verify:

  • the external domain is correct
  • the connection state is live
  • the connector is attached to the intended eshopOS store
  • the import capability set matches expectations

If any of those are wrong, the merchant should disconnect and reconnect before import work begins.

Import Job Readiness​

Before import jobs run, the system should already know:

  • which provider is connected
  • which store owns the connector
  • which external account is linked
  • which resources the import is allowed to read

That lets eshopOS separate connection management from import execution.

Suggested Merchant Workflow​

  1. Connect Shopify.
  2. Confirm the external domain shown in the connector card.
  3. Confirm the connector is live.
  4. Start an import preview.
  5. Review results before running a full import.
  6. Run the import.
  7. Open the import run details and review warnings.
  8. Confirm products, categories, warehouses, and stock landed correctly.
  9. Use rerun only after the merchant understands what is expected to update versus what is expected to be created.

This reduces accidental data creation and gives the merchant a chance to catch mapping problems early.

Operational Troubleshooting​

The connector stays inactive after configure​

Most likely causes:

  • callback URL mismatch
  • denied provider authorization
  • invalid provider client credentials
  • expired OAuth state

The wrong external shop appears​

This usually means the merchant connected the wrong shop domain during the OAuth flow. Disconnect and reconnect before starting import jobs.

Import jobs never appear​

This means the connector exists, but the import execution layer is not yet running for that store or provider.

Reconnect succeeds but data still looks stale​

A connector install and an import run are different things. Reconnection alone does not mean a new import has executed.

A rerun creates duplicate warehouses​

This usually means the original warehouse mapping was missing or the warehouse names were changed outside the connector flow. Review the current warehouse list and the latest import run before reconnecting or rerunning again.

A rerun updates products but stock still looks wrong​

Check:

  • whether Shopify locations were imported
  • whether location-level stock exists in the warehouse view
  • whether the latest run completed with inventory warnings

The connector should set location stock absolutely on rerun. If inventory still drifts, treat that as a reconciliation bug rather than continuing to rerun blindly.

Future Operations Surface​

As the connector system expands, the operations page should eventually surface:

  • recent import runs
  • warnings and partial failures
  • object counts by resource type
  • sync freshness
  • reconnect suggestions when access scope changes
  • explicit reconciliation reports for repeated runs