ShopSheetsShopSheets
HomeToolsDocumentationSupport
← Back to Documentation

Understanding Sync

This guide explains how ShopSheets keeps your data fresh and synchronized between Shopify and Google Sheets.

How ShopSheets Keeps Data Fresh

┌─────────┐                                    ┌───────────────┐
│ Shopify │ ──(webhooks)──> [ShopSheets] ──(updates)──> │ Google Sheets │
│  Store  │                                    │   Your Sheet  │
└─────────┘                                    └───────────────┘

ShopSheets syncs one-way: Shopify → Sheets (automatic)

Shopify → Sheets (Automatic)

ShopSheets uses webhooks to get notified instantly when data changes in your Shopify store.

What Are Webhooks?

Webhooks are automatic notifications from Shopify. When something happens in your store (new order, order updated, fulfillment created), Shopify sends a message to ShopSheets within seconds.

Think of webhooks like text message alerts:

  • You don't need to check your phone constantly
  • You get notified the moment something happens
  • You can act on the notification immediately

What Triggers a Sync?

ShopSheets receives webhooks for:

  • New orders (orders/create)
  • Order updates (orders/updated) - status changes, customer info, totals
  • New fulfillments (fulfillments/create)
  • Product updates (products/updated) - price, inventory, title changes

Sync Timeline

  1. Event happens in Shopify (e.g., customer places order)
  2. Shopify sends webhook (within 5-10 seconds)
  3. ShopSheets receives webhook (immediate)
  4. Queued for processing (every 5 seconds, ShopSheets processes up to 50 jobs)
  5. Google Sheets updated (within 1-2 minutes total)

Typical delay: 1-2 minutes from order creation to appearing in your sheet.

Why Not Instant?

Several steps happen behind the scenes:

  • Webhook delivery from Shopify (5-30 seconds)
  • Queue processing (5-second batches)
  • Google Sheets API call (1-2 seconds)
  • Apps Script trigger (if auto-sync enabled)

This delay is normal and ensures reliable, efficient syncing.

Queue Processing

ShopSheets uses a background job queue to handle syncs efficiently.

How It Works

  1. Webhook received → Added to queue
  2. Queue processor runs every 5 seconds
  3. Processes up to 50 jobs per batch
  4. Failed jobs automatically retry (1 min, 5 min, 15 min delays)

Why Use a Queue?

  • Handle traffic spikes - If 100 orders come in at once, queue ensures they all sync
  • Prevent Google API rate limits - Batching avoids hitting API quotas
  • Auto-retry failures - Network hiccups don't lose data

Monitoring the Queue

Check the ShopSheets dashboard:

  • Recent Activity tab - See last 50 syncs
  • Failed Syncs tab - View syncs that need retry
  • Stats - Total syncs today, success rate

Auto-Retry Logic

If a sync fails (network issue, Google API timeout), ShopSheets automatically retries.

Retry Schedule

  • First failure: Retry in 1 minute
  • Second failure: Retry in 5 minutes
  • Third failure: Retry in 15 minutes
  • After 3 failures: Marked as failed, contact support

Common Failure Reasons

  1. Google API rate limit - Rare, usually resolves in 1 minute
  2. Network timeout - Temporary connection issue
  3. Sheet deleted - If you deleted the sheet, syncs will fail (expected)
  4. Permission revoked - If you revoked Google access, reconnect account

Most failures resolve automatically within the first retry.

Sheet Structure

Understanding the sheet layout helps you work with ShopSheets data effectively.

Row Layout

Row 1: [Date Range]  [Status]    [Sort By]    [Sort Order]
Row 2: [Dropdown]    [Dropdown]  [Dropdown]   [Dropdown]
Row 3: (blank)
Row 4: (blank)
Row 5: [Order #] [Date] [Customer] [Email] [Total] [Status] ... (Headers - FROZEN)
Row 6: #1001     2024-01-15  John Doe   john@...  $99.99  Paid    ... (Data starts here)
Row 7: #1002     2024-01-14  Jane Smith jane@...  $45.00  Pending ...
...

What Gets Synced

Orders Sheet (13 columns):

  • Order Number
  • Created Date
  • Customer Name
  • Customer Email
  • Total Amount
  • Subtotal
  • Tax
  • Shipping
  • Discount
  • Financial Status (Paid, Pending, etc.)
  • Fulfillment Status (Fulfilled, Unfulfilled, etc.)
  • Tags
  • Note

Products Sheet:

  • SKU
  • Title
  • Price
  • Inventory Quantity
  • Vendor
  • Product Type
  • Tags
  • Status (Active, Draft, Archived)

Fulfillments Sheet:

  • Order Number
  • Tracking Number
  • Tracking Company (Carrier)
  • Status
  • Shipped Date
  • Line Items

Smart Caching

ShopSheets caches data to make filter changes fast and reduce API calls.

How Caching Works

Scenario 1: Expanding Date Range

  • Currently viewing: "Past 30 days" (cached)
  • Change to: "Past 90 days"
  • ShopSheets fetches days 31-90 from Shopify API
  • Merges with cached days 1-30
  • Result: Fast load, no duplicate API calls

Scenario 2: Narrowing Date Range

  • Currently viewing: "Past 90 days" (cached)
  • Change to: "Past 30 days"
  • ShopSheets filters cached data (no API call)
  • Result: Instant

Scenario 3: Changing Status Filter

  • Already have "Past 30 days" data cached
  • Change status from "All" to "Paid"
  • ShopSheets filters cached data (no API call)
  • Result: Instant

Cache Expiry

  • Lifetime: 7 days
  • After expiry: Next filter change fetches fresh data from Shopify
  • Manual refresh: Bypasses cache, always fetches fresh

Cache Benefits

  1. Faster filter changes - No waiting for API calls
  2. Reduced API usage - Fewer calls to Shopify API
  3. Better user experience - Instant response for common workflows

Manual Refresh

Sometimes you want to force a fresh fetch from Shopify, bypassing the cache.

When to Use

  • Just created an order in Shopify (want it now, not in 1-2 minutes)
  • Suspect cached data is stale
  • Modified order in Shopify Admin (outside webhook events)
  • Testing sync functionality

How to Manually Refresh

From Google Sheets:

  1. Click ShopSheets menu
  2. Select Refresh Data
  3. Wait 5-30 seconds
  4. Toast message: "Synced X orders"

From Dashboard:

  1. Click Sync Now button
  2. Wait for sync to complete
  3. Reload your sheet to see updated data

Manual refresh always fetches from Shopify API (ignores cache).

Sheets → Shopify (Coming Soon)

Two-way sync is not currently available.

Planned Features

Edit in Sheets, Sync to Shopify:

  • Update order statuses (Pending → Paid)
  • Modify product prices
  • Change inventory quantities
  • Add fulfillment tracking numbers
  • Update customer emails

How It Will Work:

  1. Edit a cell in the data area (row 6+)
  2. ShopSheets detects the change (Apps Script trigger)
  3. Sends update to Shopify API
  4. Shopify updates the data
  5. Confirmation toast: "Updated order #1001"

Safety Features:

  • Confirmation prompts for critical changes
  • Undo capability (revert to Shopify value)
  • Change log in dashboard
  • Conflict resolution (if Shopify data changed meanwhile)

Data Consistency

What Happens If...

Q: I edit data in Sheets manually? A: Your edits will be overwritten on the next sync. ShopSheets treats Shopify as the source of truth. Use columns N+ for custom data/formulas.

Q: I delete a row in the sheet? A: On the next sync, ShopSheets will re-add the order if it matches the filters. Can't delete orders from Shopify via Sheets (yet).

Q: I change filters while a sync is in progress? A: The in-progress sync completes, then auto-sync triggers for the new filters. May see two updates (1-2 seconds apart).

Q: Shopify order changes at the same time as webhook sync? A: Webhooks are sequential. The most recent webhook wins. Data stays consistent.

Performance at Scale

ShopSheets is built to handle stores of all sizes.

Benchmarks

| Order Count | Initial Sync | Subsequent Syncs | Filter Change | |-------------|--------------|------------------|---------------| | 100 orders | ~5 seconds | ~2 seconds | Instant | | 1,000 orders | ~15 seconds | ~5 seconds | Instant | | 5,000 orders | ~45 seconds | ~15 seconds | ~3 seconds | | 10,000 orders | ~2 minutes | ~30 seconds | ~5 seconds |

Factors affecting speed:

  • Number of orders in date range
  • Network latency to Google APIs
  • Cache hit rate
  • Concurrent syncs

Optimization Tips

  1. Use date range filters - "Past 30 days" vs "All time"
  2. Let cache warm up - First sync is slower, subsequent are faster
  3. Avoid "All time" for 10,000+ orders - Use "Past 90 days" unless needed
  4. Close unused sheets - Multiple large sheets can slow sync

Troubleshooting Sync Issues

Sync Not Happening

  • Check dashboard "Recent Activity" for errors
  • Verify Google account badge shows "Connected" (not "Expired")
  • Try manual refresh: ShopSheets menu → Refresh Data

Delayed Syncs (More Than 5 Minutes)

  • Shopify webhook delays (rare)
  • Check Shopify status page: status.shopify.com
  • Contact support if persistent

Data Discrepancies

  • Check filter settings (date range, status)
  • Verify data exists in Shopify Admin
  • Try manual refresh to bypass cache
  • Contact support with specific order numbers

Next Steps

Questions? Contact mail@minim-l.com

Beyond documentation

Automatic Shopify → Sheets sync.

Orders and fulfillments — always up to date in your spreadsheet.

Try ShopSheets free