Skip to main content

Shopify Integration Operational Notes

Operational guidance for teams running the ecommerce module in production.

This page focuses on observable behaviors in apps/backend/src/ecommerce/ and common implementation pitfalls.

Source-of-truth policy​

Decide and communicate inventory ownership clearly before enabling sync.

Recommended policy:

  • FlowPOS is source of truth for inventory quantity.
  • Shopify is source of truth for ecommerce order creation.

Why this matters:

  • inventory pushes run from FlowPOS -> Shopify via listeners and manual sync
  • inbound order ingestion consumes Shopify order events and decrements FlowPOS stock

If teams also edit inventory manually in Shopify, quantity drift is expected.

Idempotency and duplicate event handling​

The module deduplicates inbound orders using ecommerce_ingested_order (insertIfNew).

Implications:

  • duplicate webhook deliveries should not create duplicate downstream processing
  • poll + webhook overlap is expected and should remain safe

Operational check:

  • if duplicate imports are suspected, inspect ecommerce_ingested_order and sync logs before adding additional app-level dedupe logic.

Webhook reliability behavior​

Shopify webhook endpoint:

  • POST /ecommerce/webhooks/shopify

Current behavior:

  • invalid auth/signature issues return auth errors
  • non-auth application errors are logged and endpoint still returns 200 { ok: false }

This design avoids repeated provider retries for internal processing failures.

Operational consequence:

  • monitor application logs and sync logs; webhook HTTP status alone is not enough to detect processing quality.

Polling fallback and queue health​

Polling is implemented via BullMQ queue ecommerce-polling:

  • repeat job every 15 minutes for connected businesses
  • immediate poll trigger endpoint exists (POST /ecommerce/sync/poll)

Recommended checks:

  • queue workers are running
  • repeat jobs exist for active connections
  • lastSyncedAt advances for connected businesses

Manual sync expectations​

Manual push endpoints:

  • POST /ecommerce/sync/products
  • POST /ecommerce/sync/collections

Characteristics:

  • paginated batch processing
  • summary log entry with processed/failed counters
  • 202 accepted response (asynchronous operational result)

Support teams should consult sync logs before retrying large pushes.

Troubleshooting checklist​

  1. No connection visible
    • verify GET /ecommerce/connection?businessId=...
  2. OAuth callback errors
    • verify callback URL and query code/state
    • inspect backend logs from handleOAuthCallback
  3. Webhook not ingesting
    • verify HMAC headers and configured shop domain
    • check logs around handleWebhookEvent
  4. Inventory not updating
    • confirm product mapping exists
    • confirm inventory listener events are firing
  5. Orders not appearing
    • inspect webhook logs, then run debug poll endpoint
    • verify dedupe rows and sync log entries