← 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  │
└─────────┘                                    └───────────────┘
     ↑                                                   ↓
     └──────────────(coming soon - v1.1)────────────────┘

Current (v1.0): Shopify → Sheets (one-way, automatic) Coming Soon (v1.1): Sheets → Shopify (two-way sync)

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:

What Triggers a Sync?

ShopSheets receives webhooks for:

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:

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?

Monitoring the Queue

Check the ShopSheets dashboard:

Auto-Retry Logic

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

Retry Schedule

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):

Products Sheet:

Fulfillments Sheet:

Smart Caching

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

How Caching Works

Scenario 1: Expanding Date Range

Scenario 2: Narrowing Date Range

Scenario 3: Changing Status Filter

Cache Expiry

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

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 planned for version 1.1 (Q2 2024).

Planned Features

Edit in Sheets, Sync to Shopify:

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:

Data Consistency

What Happens If...

Q: I edit data in Sheets manually (before v1.1 two-way sync)? 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:

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

Delayed Syncs (More Than 5 Minutes)

Data Discrepancies

Next Steps

Questions? Contact mail@minim-l.com