Skip to main content

Shopify Merchant Onboarding Notes

Guidance for onboarding merchants to the current FlowPOS Shopify integration.

This page focuses on operational decisions and merchant-facing setup expectations, based on current backend behavior (apps/backend/src/ecommerce/).

What merchants need before connecting​

  • an active Shopify store
  • merchant admin access to install/authorize app permissions
  • alignment on inventory ownership and sync expectations

Merchants do not need to handle API credentials directly in FlowPOS.

Merchant connection flow (high level)​

From the merchant perspective:

  1. start connect flow in FlowPOS settings
  2. approve Shopify OAuth permissions
  3. return to FlowPOS settings page with connected status

Backend flow handling this:

  • GET /ecommerce/oauth/url
  • provider OAuth redirect
  • GET /ecommerce/oauth/callback

Critical business decisions to confirm during onboarding​

1. Store selection​

  • current integration is effectively one active store connection per business context

2. Catalog synchronization strategy​

  • clarify whether initial push should favor existing FlowPOS catalog state or preserve Shopify-side catalog details

3. Inventory source of truth​

  • define authoritative source before go-live
  • if both systems are edited manually without policy, conflicts are expected

Common post-go-live confusion points​

  • missing products after sync (mapping or eligibility assumptions)
  • inventory drift due to manual edits outside agreed source-of-truth workflow
  • delayed order appearance when webhook delivery falls back to polling interval

When diagnosing issues, start with:

  • sync log (GET /ecommerce/sync/log)
  • webhook/poll behavior checks
  • mapping consistency review