Google Sheets

How to Set Up Google Sheets Sync for Shopify Metaobjects

Connect your Google account, create a linked sheet and let auto-sync take it from there. Here's every step, plus what to do when something goes wrong.

By the Mercat Labs team5 min read

Google Sheets sync connects a metaobject type in Shopify to a live Google Sheet, so a team can bulk-edit entries in a spreadsheet instead of one at a time in the admin. This guide covers the full setup, how auto-sync behaves, and how to recover from a bad sync.

Who can use it

Google Sheets sync is available on the Pro plan, which can link one sheet, and the Scale plan, where linking sheets is unlimited — it isn't included on the Free plan. Development stores get free manual push and sync access for testing; the only part reserved for paying, live stores is the unattended auto-sync scheduler.

Step 1: Connect your Google account

From the Google Sheets sync page, click Connect Google account. This opens Google's consent screen in a new browser tab (outside Shopify's embedded frame, since Google doesn't allow its login screen inside an iframe). Approve access once; the connection is saved per store and reused for every sheet after that.

Step 2: Create a sheet for a metaobject type

Once connected, pick any metaobject type from the dropdown and click Create sheet. This does three things in one step:

  • Creates a new Google Sheet in your Drive, titled after the app and the metaobject type.
  • Fills it with every current entry of that type — or just a header row if there are none yet.
  • Applies formatting rules straight from the metaobject's definition: dropdowns for choice fields, checkboxes for booleans, and a note on every header explaining what it expects.

Each metaobject type can have one linked sheet at a time.

Step 3: Edit, then sync back

Edits happen directly in Google Sheets. When you're ready, click Sync now on the linked sheet's card to pull changes back into Shopify, or turn on auto-sync to do it automatically. Entries are matched to Shopify records by their handle column — edit a row with an existing handle to update that entry, or leave it blank on a new row to create one.

Removing a row from the sheet does not delete the entry in Shopify. Deletion in Shopify has to be a deliberate, separate action — the sync is additive and update-only by design.

Manual sync vs. auto-sync

Every linked sheet can run two ways:

  • Manual — the default. Click Sync now whenever the sheet is ready to pull in.
  • Auto-sync — pick an interval and the app checks the sheet on a schedule: every 15 minutes, every hour, or once a day.

Turning on auto-sync checks the sheet right away rather than waiting for the first interval to pass.

Only changed sheets get imported

Every time the scheduler checks a sheet, it reads the current contents and compares a hash of them against the hash saved from the last successful sync. If nothing changed, nothing happens — no import job runs, and no import counts against the plan's limit. This is why auto-sync can safely run every 15 minutes: checking is free, importing only happens when there's real work.

Imports count against plan limits

Each completed sync from a sheet, manual or automatic, counts as an import toward the store's plan limit. If a store has reached its import limit, Sync now is disabled and auto-sync checks will report that the limit was reached rather than running. Activating or upgrading a subscription restores syncing. Pushing data to the sheet, and format refreshes, are unaffected — only pulling data from the sheet into Shopify counts as an import.

Stale syncs recover automatically

A sync is marked in-progress while it runs. If a sync crashes or the server restarts mid-job, that status could otherwise get stuck. After 30 minutes, a sync still marked in-progress is treated as stale, and the next sync attempt is allowed to proceed rather than waiting forever on a job that will never finish.

Reverting a bad sync

If a sync pulled in bad data, click Revert last sync on the linked sheet's card. This:

  • Restores entries that were updated back to their previous values.
  • Deletes entries that were created by that sync.
  • Refreshes the Google Sheet afterward with the reverted Shopify data, so auto-sync doesn't immediately re-import the same mistake.

A sync can only be reverted once, and only while no other sync or revert is already running for that sheet.

Common errors and what they mean

"Google access has expired" — the merchant revoked the app's access from their Google account settings, or the refresh token otherwise stopped working. Reconnect Google account on the Google Sheets sync page restores access; nothing in Shopify or the linked sheet is affected while disconnected.

"You've reached your import limit" — each sync from a sheet counts as an import against the store's plan. Manual Sync now is blocked and auto-sync checks pause with this message until the subscription is activated or upgraded.

"A sync is already running for this sheet" — only one sync or revert can run per sheet at a time. If this appears unexpectedly and no sync is visibly in progress, wait — a crashed sync is automatically treated as stale and released after 30 minutes.

Unlinking a sheet vs. disconnecting Google

  • Unlink removes the connection between one metaobject type and its sheet. The Google Sheet itself is untouched and stays in your Drive.
  • Disconnect removes the store's Google account connection entirely, affecting every linked sheet. You can still unlink a sheet or revert a past sync even without an active Pro or Scale plan — those two actions stay available even when the feature itself is locked behind an upgrade.

Stop typing metaobjects in one at a time.

Export a definition to see the exact columns, fill it in your spreadsheet, and every row is checked before anything touches your store.