Connect a dedicated spreadsheet
Google grants the shared Editor permission across the entire spreadsheet, not only one tab or range. Use a dedicated spreadsheet without unrelated private tabs, then share it as Editor with ezformz-sheets@ezformz-integrations.iam.gserviceaccount.com.
- As the form owner, open the form in Dashboard, then open Settings → Integrations → Google Sheets.
- Paste the Google Sheet URL, choose and order the exported columns, and save.
- Choose Verify connection. This reads spreadsheet details but does not write order data.
- Choose Reconcile now to send existing orders.
Saving a first or replacement URL deliberately parks historical orders until you choose Reconcile now or Rebuild from scratch. Ordinary automatic appends cover recent orders; they are not a substitute for the explicit historical backfill.
Choose columns and understand the layout
The current standard layout keeps one row per order on the main Orders tab. Default order fields include Order ID, Date, Customer Name, Email, Status, Items, Shipping, Coupon, Total, Shipping Address, Notes, Tracking, Payment Method, Proof of Payment, Custom Fields, and a trailing Surcharges column. Order ID remains the first identity column.
The picker also creates dynamic columns:
- Customer and form-question columns use the fields configured on the form. Polls, checkboxes, multi-selects, and image choices can expand to one column per option.
- Product columns use one quantity column for each product and variant combination.
- A totals row maintains quantity sums and checkbox or poll counts.
Transaction ID, P&L Product Cost, P&L Estimated Profit, and P&L Missing Cost Items are explicit opt-in columns and are off by default. Multiple recorded payment references are combined in the Transaction ID cell. The three P&L columns use the previous standard-Sheet compatibility projection; for the full current report, use the separate dedicated P&L Sheets described in Export, preserve, schedule, or sync P&L.
Every connected spreadsheet also has derived Product Summary and Order Items tabs. They rebuild from current saved EZFormz order data and have their own version, progress, error, and retry state. A green main order row does not prove both derived tabs are current.
Older forms can remain on the legacy per-item compatibility layout. Each order then occupies a complete item block followed by a blank separator. An update rewrites the whole saved block—including items, discounts, shipping, surcharges, payment state, custom fields, and total—rather than patching a few cells. Use Rebuild from scratch when you intentionally want the current one-row-per-order layout.
Choose what updates automatically
The integration has separate controls for:
- Auto-sync new orders
- Auto-update on status / customer-info change
- Auto-update on tracking add
- Pause all auto-sync
Turning off a control changes only the Google Sheet behavior. The order change still happens in EZFormz. Pausing is useful while making manual spreadsheet changes, but EZFormz does not import those changes back. Clearing the Sheet URL stops future writes and keeps the rows already present in Google.
Catalogue changes that affect connected forms can separately dirty Product Summary. Order changes dirty both derived tabs. Stock, unit cost, and catalogue reorder changes do not by themselves rebuild Product Summary because those fields are not part of that derived sales output.
Reconcile or rebuild
Reconcile now is the normal repair action. It saves current integration settings, adds missing orders, refreshes existing complete rows or blocks in bounded passes, refreshes headers and totals, removes managed rows for orders deleted in EZFormz, and requests current Product Summary and Order Items generations. It is safe to repeat because orders are matched by ID. If the result says more rows remain, wait about a minute and run it again.
If another Sheet write owns the form, Reconcile returns a coordination message instead of recording false failures. Wait for the displayed retry time, normally about 30 seconds, then try again. If Google reports a quota or rate limit, wait at least a minute before retrying; repeated clicks do not make the provider recover sooner.
Rebuild from scratch is destructive to EZFormz-managed spreadsheet data. It removes every EZFormz data row, resets order sync coordinates and state, recreates the current Orders, Product Summary, and Order Items layout, and starts the first Reconcile pass. Large forms can require more Reconcile passes. Keep manual data outside the managed rows and tabs before rebuilding.
Read status, history, and retries
The Orders page shows a Sheet health banner with synced, waiting, failed, and pending counts. Each order has a sync control: a successful check can open the cached row, a waiting symbol can be synced manually, and a failed control shows the latest error and can retry that order.
View sync history shows the 50 most recent Sheet events for the form, with UTC timestamps and the recorded success or error detail. Check the spreadsheet itself after an asynchronous action; a returned request does not make a partially built derived tab current.
The five-minute worker retries eligible main rows and derived components with bounded backoff: about 1 minute, 5 minutes, 30 minutes, 2 hours, then 12 hours. Automatic component retries stop after five failures until a new change or manual action makes the work eligible again. Each component retries independently, so a failed Order Items build does not rewrite an already-current Product Summary or main order row.
Troubleshoot common failures
- Access denied or failed to write: share the spreadsheet with the service-account email as Editor, then run Verify connection. If access loss paused the integration, resume it after sharing.
- Header out of sync or missing columns: save the current column selection and run Reconcile now. Use Rebuild only when Reconcile cannot recover the managed layout.
- An old order is waiting: newly connected historical orders are intentionally parked. Run Reconcile or Rebuild; do not wait for the recent-order automatic append window.
- One row is missing from Google: use that order's retry control or Reconcile. A previously synced row reported as missing remains eligible for automatic repair even when the order is old.
- Totals or derived tabs look stale: run Reconcile, review sync history, and check each derived component's final result. Correct malformed order data in EZFormz rather than editing the calculated Sheet cells.
EZFormz is the source of truth. Correct an order in EZFormz and reconcile rather than treating a direct spreadsheet edit as an order update.