Saltar al contenido principal

Shopify Partner Setup (FlowPOS Ecommerce)

Setup checklist for engineering teams configuring Shopify credentials for the FlowPOS ecommerce module.

Codepaths covered:

  • apps/backend/src/ecommerce/interfaces/ecommerce.controller.ts
  • apps/backend/src/ecommerce/application/ecommerce.service.ts
  • apps/backend/src/ecommerce/infrastructure/shopify/shopify.adapter.ts
  • apps/backend/src/ecommerce/infrastructure/shopify/shopify-webhook.controller.ts

What you need​

  • Shopify Partner account
  • Shopify app credentials (client ID + client secret)
  • one or more dev/test stores
  • public HTTPS backend URL for OAuth callback and webhook delivery

Required app configuration​

1) OAuth callback URL​

FlowPOS callback endpoint:

GET /ecommerce/oauth/callback

Set allowed redirect URL(s) to your backend base URL + path, for example:

  • https://api-staging.flowpos.app/ecommerce/oauth/callback
  • local/dev tunnel equivalent when testing locally

EcommerceController.oauthCallback then redirects to PWA_BASE_URL/settings/ecommerce.

2) API scopes​

ShopifyAdapter defaults to:

  • read_products
  • write_products
  • read_inventory
  • write_inventory
  • read_orders
  • write_orders

These are configurable via SHOPIFY_APP_SCOPES.

3) Webhook endpoint​

FlowPOS webhook endpoint:

POST /ecommerce/webhooks/shopify

Topics currently registered by adapter:

  • orders/create
  • inventory_levels/update

registerWebhooks is called after OAuth exchange in handleOAuthCallback.

Validation checklist after setup​

  1. call GET /ecommerce/oauth/url with provider=shopify, shopDomain, businessId
  2. complete Shopify consent flow
  3. verify callback redirects with ?connected=true
  4. confirm GET /ecommerce/connection returns active connection
  5. verify webhooks exist in Shopify and point to FlowPOS endpoint
  6. trigger a test sync (POST /ecommerce/sync/products)

Common pitfalls​

  • callback URL mismatch between app config and APP_BASE_URL
  • missing scopes causing product/order operations to fail
  • non-HTTPS callback/webhook URL in environments where Shopify requires HTTPS
  • assuming webhook registration alone is enough without polling fallback

EcommerceService always keeps polling support as a fallback path.