Skip to main content

Merchant Connectors

Merchant Connectors let a store owner connect another commerce platform to eshopOS and bring structured store data into the current store without rebuilding everything manually.

This feature is not a marketplace sync and it is not a generic API playground. It is a merchant migration and import workspace built for store-to-store transfer into eshopOS.

What a Connector Is​

A connector is a store-scoped integration record that tells eshopOS:

  • which external platform is connected
  • which external shop or account is linked
  • which permissions were granted
  • when the connection was last active
  • what import work has already been run

Every connector is tied to one store_id. A connector for one store cannot be reused by another store.

What Connectors Are For​

Use connectors when a merchant wants to:

  • move products into eshopOS from another platform
  • bring collections or categories across
  • reuse external product media
  • carry inventory structure forward
  • bring warehouse/location structure forward
  • reduce manual migration time during onboarding

What Connectors Are Not​

Connectors are not the same thing as:

  • public API keys
  • OAuth apps created by developers for third-party access into eshopOS
  • payment providers
  • shipping providers
  • marketplace channels like Amazon or eBay

Those are separate integration types with different trust models and different operational risks.

How the Connector Flow Works​

The connector flow has four stages.

1. Configure​

The merchant opens the connector workspace, chooses a provider, and starts the connection flow. For Shopify, this means entering the shop domain and sending the merchant through Shopify OAuth.

2. Authorize​

The provider returns an authorization code to the eshopOS backend. The backend exchanges it for a provider access token and stores the resulting install as a store-scoped connector record.

3. Inspect​

Once connected, the merchant sees the external account name, the external domain, the granted scope set, and the current connector state.

4. Import​

Import jobs use the connector to fetch external resources and transform them into eshopOS records. Import jobs are separate from the connector itself so that the connection stays stable even if one import run fails.

Store Isolation Model​

Connector security depends on strict tenancy boundaries.

  • one store can have one connector record per provider
  • OAuth state is tied to the store that initiated the connect flow
  • provider tokens are stored on the backend only
  • merchant UI can see connector status, but not the raw provider access token
  • import jobs are filtered by the same store context as the connector

This model prevents one merchant from seeing or using another merchant’s external platform connection.

Connector Status Meanings​

Live​

The provider account is connected and eshopOS has a valid install record for that store.

Inactive​

The provider is not connected, was disconnected, or the setup has not been completed yet.

Failed​

The connection attempt or callback completed with an error and needs to be retried.

Why Connectors Are a Separate Module​

eshopOS already contains developer OAuth and public API tooling. That tooling is for outside applications calling into eshopOS.

Merchant connectors solve the opposite problem: eshopOS calling out to an external platform on behalf of a merchant store.

That inversion is important enough that connectors need their own backend module, routes, storage, and audit history instead of being mixed into developer apps.

Current Scope​

The current connector foundation supports:

  • store-scoped connection records
  • provider OAuth state tracking
  • provider callback handling
  • connection status tracking
  • import-job storage
  • rerun-oriented import reconciliation
  • warehouse-aware inventory import for supported providers

The import execution layer sits on top of that foundation.