G3N Retail Stack Story

Appearance

Shopify Legacy Connector (SLC) ​

Status: Implemented (Phase 7 complete — OAuth, inbound, outbound, eventing, KMS tokens).

Purpose ​

SLC is the Shopify legacy connector. It pushes product and stock data outbound to Shopify stores and receives order events inbound for inventory impact. It bridges the gap between the g3nretailstack headless platform and existing Shopify storefronts, enabling merchants to maintain their Shopify presence while centralizing inventory and product management in g3nretailstack.

Goals ​

  • Outbound sync: push product catalog (styles, variants, prices, images) and stock levels to Shopify.
  • Inbound sync: receive Shopify order/refund/edit events and translate them into ICS stock movements.
  • Support two channel types: Standard (full product lifecycle with ~45 config flags) and Custom (variant-level updates only).
  • Provide config-driven behavioral flexibility per channel (throttle policy, variant scope, facility mapping, price source).
  • Handle Shopify OAuth install flow (custom distribution model — one app per store/Plus org).

Non-goals ​

  • SLC does not own product truth (owned by PVM).
  • SLC does not own inventory (owned by ICS).
  • SLC does not own pricing (owned by PPM).
  • SLC does not replace a future modernized Shopify sales-channel integration.

Key capabilities ​

  • Outbound product sync: Event-driven (PVM/ICS change events trigger sync) plus direct Lambda invoke for force-sync. Maps g3nretailstack styles/variants to Shopify products/variants via productCreate/productVariantsBulkUpdate GraphQL mutations.
  • Outbound inventory sync: Uses Shopify inventorySetQuantities with ignoreCompareQuantity for reliable stock pushes. Multi-facility support (primary + contributing facilities per channel).
  • Inbound order events: Shopify EventBridge partner event source delivers webhook events. Five topics: orders/create, orders/updated, refunds/create, orders/edited, reverse_fulfillment_orders/dispose. Events translate to ICS stock card entries with SLC-specific reason codes.
  • OAuth install flow: Shopify Partner app with custom distribution. OAuth redirect/callback Lambdas handle HMAC validation, auth code exchange, scope validation, connectivity testing, and KMS token encryption — all automatic, zero merchant involvement.
  • Credential security: Shopify access tokens encrypted at rest via KMS (alias/g3nretailstack-slc-tokens). Supports both static (legacy) and expiring (1h access + 90d refresh) token modes.
  • Audit trail: DDB-based queryable audit (90-day TTL) plus S3 full-payload archive (1-year retention). Three query dimensions: by variant, by Shopify variant ID, by SKU.
  • Throttle-aware: Lambda exits on Shopify 429, adjusts SQS visibility timeout, retries later (zero cost during backoff).

Cross-service interactions ​

  • PVM: Reads product/variant data for outbound sync. Listens to PVM DynamoDB Stream events.
  • ICS: Reads stock positions for inventory sync. Writes inbound stock movements from Shopify orders. Listens to ICS events.
  • PPM: Reads price lists for outbound price sync.
  • OPS: Registered in vacuum manifest (slc_main table). Supports vacuum/org action.
  • EventBridge: Publishes to events bus. Receives from Shopify partner event source.

Contract surface ​

  • 28 admin actions via single POST / dispatch endpoint (session auth).
  • 2 public OAuth endpoints: GET / (redirect) and GET /oauth/callback (token exchange).
  • SQS sync queue for async outbound operations.
  • Full contract details: SLC Surfaces | SLC Calls | SLC OpenAPI