← Back to Documentation

Apps Script Setup

This guide explains the Google Apps Script integration that powers ShopSheets' auto-sync features.

What is Apps Script?

Google Apps Script is Google's automation tool for Sheets, Docs, and other Google Workspace apps. It lets you run custom code directly in your spreadsheets.

ShopSheets uses Apps Script to:

• Add a custom ShopSheets menu to your toolbar
• Enable auto-sync when filters change
• Handle manual refresh requests
• Show toast notifications ("Syncing orders...", "Synced 50 orders")

You don't need to write any code. ShopSheets automatically deploys the script when you create a sheet.

---

Automatic Installation

The Apps Script project is deployed automatically when you create a sheet from the ShopSheets dashboard.

What Gets Installed

1. Apps Script Project named "ShopSheets Sync"
2. Custom Menu - "ShopSheets" appears in the toolbar
3. Menu Items:
   • Refresh Data
   • Setup Auto-Sync
4. Configuration - API key and spreadsheet ID (pre-configured)

No manual setup required. Everything works out of the box.

---

ShopSheets Menu

After creating a sheet, you'll see a ShopSheets menu in the toolbar (next to Help).

Menu Items

1. Refresh Data

What it does: Manually triggers a sync from Shopify to update your sheet with the latest data.

When to use:

• Just created an order in Shopify (want it now, not in 1-2 minutes)
• Suspect data is stale
• Want to force a fresh fetch (bypasses cache)

How to use:

1. Click ShopSheets → Refresh Data
2. Wait 5-30 seconds (depending on data volume)
3. Toast message appears: "Syncing orders..."
4. On completion: "Synced X orders" or "Synced X orders (from cache)"

Behind the scenes:

• Apps Script calls ShopSheets API
• ShopSheets fetches data from Shopify based on current filters
• Google Sheets updates rows 6+ with new data
• Cache is updated

---

2. Setup Auto-Sync

What it does: Enables automatic data refresh when you change filters.

When to use:

• First time setting up the sheet (recommended)
• After granting Apps Script permissions
• If auto-sync stopped working

How to use:

1. Click ShopSheets → Setup Auto-Sync
2. Grant permissions when prompted (one-time):
   • "See, edit, create, and delete all your Google Sheets spreadsheets"
   • "Connect to an external service"
3. Toast message: "Auto-sync enabled"
4. Now when you change filters, data refreshes within 2 seconds automatically

Behind the scenes:

• Apps Script installs an onEdit trigger
• Trigger watches for changes to row 2 (filter dropdowns)
• When a filter changes, automatically calls Refresh Data
• No manual refresh needed

Recommended: Enable auto-sync for the best experience.

---

Enabling Auto-Sync Triggers

Auto-sync requires one-time permission grant to install triggers.

Permission Flow

1. Run Setup Auto-Sync (first time)
2. Authorization popup appears:
   • "ShopSheets Sync wants to access your Google Account"
   • Shows required permissions
3. Review permissions:
   • See, edit, create, and delete spreadsheets
   • Connect to an external service (ShopSheets API)
4. Click "Allow"
5. Auto-sync enabled - Filters now trigger automatic refresh

Why These Permissions?

• Spreadsheets access: To detect filter changes and update data
• External service: To call ShopSheets API for fresh data

ShopSheets only accesses the sheet it created. We cannot see other files in your Google Drive.

Revoking Permissions

If you want to revoke Apps Script permissions:

1. Go to Google Account Permissions
2. Find "ShopSheets Sync"
3. Click Remove Access

Note: This disables auto-sync. Manual refresh still works.

---

Troubleshooting Apps Script

No "ShopSheets" Menu in Toolbar

Possible causes:

1. Apps Script not loaded yet (can take 30 seconds on first open)
2. Browser cache issue
3. Apps Script deployment failed

Solutions:

1. Reload the sheet - Press Ctrl/Cmd + R
2. Check Extensions → Apps Script:
   • Should see "ShopSheets Sync" project
   • If missing, script didn't deploy correctly
3. Try incognito mode - Rules out browser extension conflicts
4. Create new sheet - If problem persists, create a new sheet from dashboard

---

"Script Not Configured" Error

What you see: Error message: "Script not configured. API configuration is missing."

Cause: Apps Script project is missing the API key (rare deployment issue)

Solution:

1. Note your spreadsheet ID (from the URL: https://docs.google.com/spreadsheets/d/{SPREADSHEET_ID})
2. Contact mail@minim-l.com with the spreadsheet ID
3. We'll redeploy the script with the correct configuration

Temporary workaround:

• Use manual refresh from the dashboard instead of the sheet menu
• Create a new sheet (this deploys a fresh script)

---

Permission Denied Error

What you see: "You need authorization to perform this action"

Cause: Apps Script permissions not granted or revoked

Solution:

1. Click ShopSheets → Setup Auto-Sync
2. Grant permissions when prompted
3. Click "Allow" (not "Deny")

If already granted:

• Check Google Account Permissions
• Ensure "ShopSheets Sync" is listed
• If missing, run Setup Auto-Sync again

---

Auto-Sync Not Working After Filter Change

What you see: Change a filter dropdown, but data doesn't refresh

Possible causes:

1. Auto-sync trigger not installed
2. Permissions denied
3. Trigger was manually deleted

Solution:

1. Run: ShopSheets → Setup Auto-Sync
2. Grant permissions if prompted
3. Change a filter to test - should sync within 2 seconds

Check trigger installation:

1. Open Extensions → Apps Script
2. Click Triggers (clock icon on left)
3. Should see a trigger for onEdit
4. If missing, run Setup Auto-Sync again

---

"Syncing Orders..." Appears But Nothing Happens

What you see: Toast message "Syncing orders..." but sheet doesn't update

Possible causes:

1. Sync already in progress (wait for completion)
2. Data is current (served from cache)
3. Apps Script timeout (rare)

Solutions:

1. Wait 30 seconds - Large datasets take time
2. Check for completion toast - "Synced X orders" or "Synced X orders (from cache)"
3. If "(from cache)" - Data is already up-to-date, no changes needed
4. Try manual refresh from dashboard - Bypasses Apps Script

---

Toast Messages Keep Appearing

What you see: "Syncing orders..." toast appears repeatedly

Cause: Circular trigger loop (rare Apps Script bug)

Solution:

1. Reload the sheet (Ctrl/Cmd + R)
2. If persists, disable auto-sync:
   • Open Extensions → Apps Script
   • Click Triggers → Delete the onEdit trigger
3. Use manual refresh instead: ShopSheets → Refresh Data
4. Contact support if issue persists

---

Viewing Apps Script Logs

For advanced troubleshooting, you can view Apps Script execution logs.

How to Access Logs

1. Open your sheet
2. Click Extensions → Apps Script
3. The script editor opens
4. Click Executions (clock icon on left)
5. See recent script runs with status (Success, Failure)

What to Look For

• Status: Success - Script ran correctly
• Status: Failure - Click for error details
• Error messages - Share with support for diagnosis

Common errors:

• "Exception: Service invoked too many times" - Google API rate limit (retry in 1 minute)
• "Exception: Request failed" - Network timeout (retry manually)

---

Advanced: Customizing the Script

Not recommended for most users. Modifying the script can break syncing.

If You Must Customize

1. Open Extensions → Apps Script
2. Edit the code
3. Do NOT change:
   • API key configuration
   • Function names (onOpen, refreshData, setupAutoSync)
   • API endpoint URLs
4. Safe to add:
   • Custom menu items (your own functions)
   • Additional logging

If you break the script:

• Create a new sheet from the dashboard (fresh deployment)
• Contact support for help

---

Apps Script Quotas

Google Apps Script has daily quotas that affect how often you can sync.

Relevant Quotas (Free Google Account)

• UrlFetch calls: 20,000 per day
• Script runtime: 6 minutes per execution
• Triggers: 20 time-driven triggers per script

ShopSheets usage:

• Each manual refresh: 1 UrlFetch call
• Each auto-sync: 1 UrlFetch call
• Each execution: ~2-5 seconds

You're unlikely to hit quotas unless:

• Changing filters hundreds of times per day
• Multiple users editing the same sheet simultaneously

If you hit a quota:

• Error: "Service invoked too many times"
• Wait until next day (quotas reset at midnight Pacific Time)
• Use dashboard for manual syncs (doesn't count toward Apps Script quotas)

---

Security & Privacy

What Data Does the Script Access?

• Your spreadsheet - To read filters and write order data
• ShopSheets API - To fetch data from Shopify

The script does NOT:

• Access other files in your Drive
• Send data to third parties
• Store your data (all handled by ShopSheets backend)

Script Source Code

The script source is visible:

1. Open Extensions → Apps Script
2. Review the code yourself

Script hash verification:

• Each deployment includes a hash comment at the top
• Verifies the script matches ShopSheets official version

---

Uninstalling the Script

If you want to remove the Apps Script project:

1. Open Extensions → Apps Script
2. Delete the "ShopSheets Sync" project
3. The ShopSheets menu disappears
4. Auto-sync stops working

Effects:

• Manual refresh from sheet menu no longer works
• Filters won't auto-sync
• Sheet remains in Drive with current data
• Can still use dashboard for syncs

To reinstall:

• Create a new sheet from the dashboard (fresh script deployment)

---

Next Steps

• Using Filters - Learn how to use the filter dropdowns
• Understanding Sync - How real-time sync works
• Troubleshooting - Fix common issues

Questions about Apps Script? Contact mail@minim-l.com