Skip to main content

Shopify Sync – Technical Details

This article explains what data Synplex syncs from your Shopify store, which permissions are needed, and why.

Overview​

When you connect Synplex to Shopify, we request specific permissions to read and monitor your store's product, inventory, and order data. This page breaks down exactly what we access and why.

Access Scopes (Permissions)​

Synplex requests these permissions upon installation:

read_products
├─ Why: Read your product catalog (names, descriptions, types)
└─ Used for: Inventory management, product matching, reporting

read_inventory
├─ Why: Read current stock levels across all locations
└─ Used for: Real-time inventory status, stockout alerts, supply planning

read_locations
├─ Why: Identify your warehouses and sales channels
└─ Used for: Multi-location inventory tracking, location-specific orders

read_orders
├─ Why: Read completed and archived orders for historical data
└─ Used for: Sales forecasting, demand analysis, sales trends

read_all_orders
├─ Why: Access full order history including draft orders
└─ Used for: Complete demand visibility, edge cases

read_fulfillments
├─ Why: Track which orders have been fulfilled
└─ Used for: Understand incoming stock, order status monitoring

read_merchant_managed_fulfillment_orders
├─ Why: Read fulfillment data for merchant-managed locations
└─ Used for: Track stock movements, receiving status

read_third_party_fulfillment_orders
├─ Why: Read fulfillment data for third-party fulfillment (3PL/dropship)
└─ Used for: Multi-channel inventory visibility, 3PL tracking

What we DON'T access:

  • Customer data (names, emails, addresses)
  • Payment information (credit cards, billing data)
  • Admin passwords or API credentials
  • Private app tokens

Webhook Topics (Real-Time Events)​

Webhooks trigger actions whenever specific events occur in Shopify. Synplex listens to these:

Product & Catalog Changes​

products/create
├─ When: You add a new product to Shopify
└─ Action: Synplex creates product record, syncs to inventory table

products/update
├─ When: You edit product details (name, description, type, vendor)
└─ Action: Synplex updates product record instantly

products/delete
├─ When: You delete a product
└─ Action: Synplex marks as archived (not deleted, preserved for history)

collections/create
├─ When: You create a new collection
└─ Action: Synplex syncs collection tags for filtering

collections/update
├─ When: You edit collection membership or details
└─ Action: Synplex updates product associations

collections/delete
├─ When: You delete a collection
└─ Action: Synplex updates product records accordingly

Inventory & Location Changes​

locations/create
├─ When: You add a new warehouse or sales channel
└─ Action: Synplex creates location record, begins tracking inventory there

locations/update
├─ When: You edit location details (name, address, type)
└─ Action: Synplex updates location info

locations/activate
├─ When: You activate a previously inactive location
└─ Action: Synplex begins tracking inventory levels

locations/deactivate
├─ When: You deactivate a location (e.g., close warehouse)
└─ Action: Synplex marks as inactive, stops ordering recommendations

locations/delete
├─ When: You delete a location
└─ Action: Synplex archives, preserves historical data

inventory_levels/connect
├─ When: A new inventory tracking connection is created
└─ Action: Synplex registers the SKU-location pairing

inventory_levels/update
├─ When: Stock quantity changes (sales, restocking, adjustments)
└─ Action: Synplex updates on-hand inventory instantly, recalculates statuses

inventory_levels/disconnect
├─ When: A SKU is no longer tracked at a location
└─ Action: Synplex stops monitoring that variant at that location

inventory_items/create
├─ When: New variant created (new size, color, style)
└─ Action: Synplex creates variant record

inventory_items/update
├─ When: Variant details change (barcode, SKU, cost, weight)
└─ Action: Synplex updates variant record

inventory_items/delete
├─ When: Variant is deleted
└─ Action: Synplex archives variant record

Order & Subscription Events​

shop/update
├─ When: Your shop settings change (name, currency, timezone)
└─ Action: Synplex updates shop metadata

app/uninstalled
├─ When: You uninstall Synplex
└─ Action: Synplex stops syncing, cleans up webhooks

app_subscriptions/update
├─ When: Your billing plan changes or expires
└─ Action: Synplex updates feature access accordingly

Data Models (What We Store)​

Synplex creates records for these Shopify objects in your Gadget database:

Core Product Data​

shopifyProduct
├─ Product ID, title, type, vendor
├─ Tags, status (active/archived)
├─ Descriptions, images
├─ Revenue and sales data (calculated)
└─ Used for: Inventory management, reporting, filtering

shopifyProductVariant
├─ Variant ID, product ID, SKU, barcode
├─ Size, color, style (as option values)
├─ Unit cost (if available from Shopify)
├─ Pricing and weight
└─ Used for: SKU-level inventory tracking, PO creation

shopifyInventoryItem
├─ Inventory item ID, variant ID
├─ Tracking status, SKU
├─ Cost basis, requires shipping, requires tax
├─ Created/updated timestamps
└─ Used for: Inventory integrity, cost data

Location & Stock Data​

shopifyLocation
├─ Location ID, name, type (warehouse, pop-up, etc.)
├─ Address, latitude/longitude
├─ Fulfillment service info
├─ Active/inactive status
└─ Used for: Multi-location tracking, supply planning

shopifyInventoryLevel
├─ Inventory level ID, inventory item ID, location ID
├─ On-hand quantity, available quantity
├─ Updated timestamp
└─ Used for: Real-time stock status, stockout alerts, supply plan

shopifyInventoryQuantity
├─ Linked to inventory levels + locations
├─ Historical snapshots (for trend analysis)
└─ Used for: Inventory variance reporting, historical comparison

Orders & Collections​

shopifyCollection
├─ Collection ID, title, handle
├─ Description, image
├─ Created/updated timestamps
└─ Used for: Product grouping, filtered analysis

shopifyCollect
├─ Association between product and collection
└─ Used for: Collection-based filtering, bulk operations

(Order data is read but not stored in detail — only aggregated for demand analysis)

Billing & Configuration​

shopifyAppSubscription
├─ Subscription plan ID, status (active/expired/cancelled)
├─ Billing cycle info
└─ Used for: Feature gating, plan enforcement

Data Flow: How It Works​

Day 1: You install Synplex
├─ Step 1: Grant access scopes
├─ Step 2: Synplex reads current products, inventory, locations
├─ Step 3: Creates initial records in your Gadget database
└─ Step 4: Registers webhooks for real-time updates

Daily: Inventory changes occur
├─ Sale happens → inventory_levels/update webhook fires
├─ Synplex receives webhook → updates shopifyInventoryLevel record
├─ You see updated stock in Synplex table instantly
└─ Supply plan recalculates, alerts update

Weekly: You add a new product
├─ products/create webhook fires
├─ Synplex creates shopifyProduct + shopifyProductVariant records
├─ Product appears in Synplex inventory table
├─ You configure supplier, costs, etc.

Monthly: You adjust forecasts
├─ Synplex tracks your adjustments
├─ Supply plan recommendations update
└─ Reports show performance vs. forecast

Why We Need Each Permission​

Inventory Accuracy​

Permissions: read_inventory, read_locations, inventory_levels/update

Why: Stock levels change constantly (orders, restocking, adjustments). Without real-time sync, Synplex would show stale data. You'd miss stockouts and over-order.

Demand Forecasting​

Permissions: read_orders, read_all_orders

Why: To understand sales patterns (which products, which seasons), Synplex analyzes order history. This powers demand forecasts and stockout predictions.

Multi-Location Support​

Permissions: read_locations, locations/, inventory_levels/

Why: If you have multiple warehouses or sales channels, Synplex tracks inventory at each location. Different locations may have different stock levels and reorder policies.

Product Matching​

Permissions: read_products, products/, variants/

Why: Synplex matches your Shopify products to supplier catalogs, cost data, and your internal naming. When you add a product, we create records automatically.

Order Fulfillment Visibility​

Permissions: read_fulfillments, read_merchant_managed_fulfillment_orders, read_third_party_fulfillment_orders

Why: To understand incoming stock and receiving timing. If you use 3PLs or multiple fulfillment channels, we track which orders are fulfilled where and when stock arrives.

Security & Privacy​

  • No customer data: We never access customer names, emails, addresses, or payment info.
  • No passwords: We use OAuth—you never share your password.
  • Read-only: We read Shopify data; we don't modify your store directly.
  • Webhooks are encrypted: Data in transit is secured.
  • Access can be revoked: Uninstall Synplex anytime to disconnect.

Troubleshooting Sync Issues​

"My new product isn't showing in Synplex"​

Possible causes:

  • Webhook delay (usually <1 minute)
  • Product marked as draft or archived
  • Variant not created yet

Solution: Wait 1 minute, refresh. Check product status in Shopify (should be Active).

"Inventory quantity isn't updating"​

Possible causes:

  • Inventory tracking disabled for that variant
  • Location deactivated
  • Webhook not registered

Solution: Check Shopify variant settings. Ensure location is active and variant has inventory tracking ON.

"I don't see all my locations"​

Possible causes:

  • Location is deactivated in Shopify
  • Webhook didn't fire when location was created

Solution: Activate locations in Shopify. Reinstalling Synplex will sync all active locations.