> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/destinations/categories/spreadsheets/google_sheets.md).
# Google Sheets
Google Sheets is a cloud-based spreadsheet tool that lets you store, organize, and analyze data in your browser. As a Coupler.io destination, it's one of the most popular places to send data — great for building reports, dashboards, and automated data backups without any engineering work.
## Why use Google Sheets as a destination?
* **No setup overhead** — connect with a single OAuth sign-in and start sending data in minutes
* **Works with any Coupler.io source** — from Airtable and HubSpot to Facebook Ads and Salesforce, any source can flow into Google Sheets
* **Flexible write modes** — replace your data on every run for up-to-date reports, or append rows to build a running history
* **Formulas stay intact** — control exactly which cells Coupler.io writes to, so your formulas and formatting in adjacent columns are preserved
* **Dynamic sheet names** — use macros to auto-create a new sheet on every run (e.g., one sheet per day)
## Prerequisites
* A Google account with access to Google Sheets
* The destination spreadsheet must already exist, or Coupler.io will create a new sheet tab inside an existing file
* Your Google account must have edit access to the destination spreadsheet
## Quick start
{% hint style="success" %}
If you just want to get data flowing fast, connect your Google account, pick an existing spreadsheet, and run the data flow. You can fine-tune cell ranges and write modes after your first successful run.
{% endhint %}
## How to connect
{% stepper %}
{% step %}
**Add a source to your data flow.** In Coupler.io, create a new data flow and configure your source — this can be any supported integration like Airtable, HubSpot, Facebook Ads, or any other source. You can add multiple sources to a single data flow.
{% endstep %}
{% step %}
**Select Google Sheets as your destination.** In the Destination section of your data flow, choose Google Sheets from the list of available destinations.
{% endstep %}
{% step %}
**Connect your Google account.** Click **Connect** and sign in with the Google account that has access to your destination spreadsheet. Review the requested permissions (Coupler.io needs access to read and write spreadsheet data) and approve them. Once authorized, the connection is saved for future data flows.
{% endstep %}
{% step %}
**Select your spreadsheet and sheet tab.** Use the dropdown to pick an existing spreadsheet from your Google Drive. Then select the sheet tab where data should land — or type a new tab name and Coupler.io will create it automatically on first run.
{% endstep %}
{% step %}
**Run your data flow.** Click **Run** to execute your first manual import. Once it completes successfully, your data will appear in the destination sheet. You can then review the results and set up a schedule.
{% endstep %}
{% endstepper %}
## Supported features
| Feature | Supported |
| ------------------------- | --------- |
| Replace mode | Yes |
| Append mode | Yes |
| Automatic scheduling | Yes |
| Type enforcement | No |
| Dynamic sheet name macros | Yes |
| Templates | Yes |
| Cell range targeting | Yes |
## Google Sheets common issues
### Connection issues
"The API developer key is invalid" error when selecting a spreadsheet
This is a known Google issue that occurs when your browser isn't actively signed in to the Google account you connected to Coupler.io.
**Fix:** Open a new browser tab and sign in to the correct Google account at [accounts.google.com](https://accounts.google.com). Then return to Coupler.io and try selecting the spreadsheet again. If the issue persists, try clearing your browser cookies or using an incognito window to re-authorize.
"Access token is invalid" (401 error)
This usually means the OAuth connection between Coupler.io and your Google account has expired or been revoked.
**Fix:** Go to the Destinations tab in Coupler.io, find your Google Sheets connection, and reconnect it by signing in to Google again. Also check that Coupler.io still has permission in your [Google account security settings](https://myaccount.google.com/permissions).
"The service is currently unavailable" error
This means the Google Sheets API is temporarily unavailable — usually due to a brief outage or maintenance.
**Fix:** Wait a few minutes and retry the data flow manually. If the error continues, check whether the destination spreadsheet opens normally in your browser. If you're running many data flows to the same sheet simultaneously, try staggering their schedules to reduce API load.
Unable to find or select the destination spreadsheet
Coupler.io can only access spreadsheets that belong to or are explicitly shared with the connected Google account.
**Fix:** Make sure the spreadsheet is owned by — or shared with edit access to — the Google account you connected. Spreadsheets in shared drives may also require additional permissions.
### Data issues
Fewer rows than expected appear in the destination sheet
If you defined a cell range (e.g., `C1:F50`) in Replace mode, Coupler.io will only write data within that range. Rows or columns beyond the range boundaries are silently dropped.
**Fix:** Either expand your defined range to accommodate all expected data, or remove the range limit and use just a starting cell (e.g., `C1`) so Coupler.io writes as many rows and columns as the source provides.
Numbers are imported as text or display incorrectly
Coupler.io expects numerical data in standard programming format — plain digits or digits with a dot as the decimal separator (e.g., `2345123.00`). If your source uses locale-specific formatting like `2.345.123,00`, the import may produce text values instead of numbers.
**Fix:** Ensure your source data uses dot notation for decimals before it reaches Coupler.io. Coupler.io will then automatically convert the values to match your spreadsheet's locale settings.
Filters, formatting, or formulas are removed after a run
In Replace mode, Coupler.io overwrites the data range it controls. Filters applied to those columns and any formatting in the written cells will not be preserved.
**Fix:**
* Place formulas in columns to the **left** of your data start cell — Coupler.io writes rightward from the starting cell and won't touch those columns.
* If you need filters, consider reapplying them via a Google Sheets macro after each run, or use a separate summary sheet that references your data range with `IMPORTRANGE`.
* For preserving formatting alongside imported data, use the **Append** mode — existing rows are not modified.
{% hint style="warning" %}
Coupler.io does not currently preserve column filters on re-import. If maintaining filters is critical, use a separate reference sheet for analysis.
{% endhint %}
"This action would increase the number of cells above the 10,000,000 limit"
Google Sheets caps every spreadsheet at 10 million cells total — across all tabs. This error has nothing to do with how many rows your data flow imports; it's about the total cell count in the file.
**Fix:** Open the destination spreadsheet and delete unused sheet tabs, empty rows, or empty columns that inflate the cell count. If the spreadsheet is already heavily used, create a fresh spreadsheet as the destination.
{% hint style="danger" %}
This limit is per-spreadsheet and cannot be increased. Repeatedly appending data to a large file will eventually hit this ceiling.
{% endhint %}
Google API 500 "Internal error encountered"
This error typically points to an overloaded or formula-heavy spreadsheet, a broken formula, or a temporary Google API issue.
**Fix:**
* Check whether the destination spreadsheet opens and loads quickly in your browser. Slow loading or formula errors are a red flag.
* Clean up the spreadsheet: remove broken formulas, unused sheets, and any cells that reference external data that may be failing.
* If the problem persists, try pointing the data flow to a fresh, empty spreadsheet to confirm the issue is with the file rather than the data flow itself.
### Permission errors
Data flow fails because Coupler.io can't write to the sheet
Coupler.io needs **Editor** access to the destination spreadsheet. Viewer or Commenter access is not sufficient.
**Fix:** In Google Sheets, open the **Share** dialog and confirm the connected Google account has Editor permissions. If the sheet is protected (via **Data > Protect sheets and ranges**), remove or adjust the protection rules to allow Coupler.io to write.
Plan limit reached — can't add a new destination sheet
Coupler.io plans have a limit on the number of destination connections. Hitting this limit blocks new destination setup.
**Fix:** Review your active data flows and remove any that are no longer needed, or upgrade your Coupler.io plan to increase your limits.
## Google Sheets FAQ
What's the difference between Replace and Append mode?
**Replace** deletes all previously imported data in the target area and writes fresh data from your source on every run. Use this when you want your sheet to always reflect the current state of your source — for example, a live CRM contacts list.
**Append** adds new rows below the existing data without touching what's already there. Use this when you want a running history — for example, daily ad spend records where you never want to lose older entries.
If you're using Append and want to avoid duplicates, make sure your source query filters to only new data (e.g., records created since the last run).
How do I keep my formulas safe when Coupler.io imports data?
Set your **cell address** to a column that leaves space for your formulas. Coupler.io writes data to the right starting from the cell you specify, so placing formulas in columns to the **left** of the start cell keeps them untouched.
For example, if you set the cell address to `C1`, columns A and B are completely free for your own formulas and labels.
Can I target a specific cell range instead of writing from a single starting cell?
Yes. Instead of a single cell like `A1`, you can enter a range like `C1:F50` in the cell address field. This tells Coupler.io to write only within those boundaries — useful when you want imported data sandwiched between existing columns.
Just make sure the range is large enough for your data. In Replace mode, any data outside the defined range will be cut off.
{% hint style="info" %}
See the **Update Google Sheets destination without data overwriting** article for a full table of supported range formats and examples.
{% endhint %}
Can I create a new sheet tab automatically on every run?
Yes — use a macro in your destination sheet name. For example, entering `orders_{{today}}` as the sheet name will create a new tab named with today's date on each run. Pair this with a daily schedule and you get one organized tab per day automatically.
Coupler.io supports several macros for dynamic naming. Check the dedicated macros guide for the full list of options.
{% hint style="warning" %}
Do not use date macros like `{{today}}` if you just want data refreshed in the same sheet — that will create a new tab on every run rather than updating the existing one.
{% endhint %}
Can I import data from multiple sources into the same Google Sheet?
Yes, in two ways. First, a single data flow supports multiple sources — you can combine them using Join, Append, or Aggregate transformations before sending the result to one sheet tab. Second, you can create separate data flows that each write to different tabs within the same spreadsheet.
Will Coupler.io overwrite data in cells I didn't intend to change?
In Replace mode, Coupler.io clears and rewrites everything starting from your defined cell or range. It does not touch cells outside that area. To protect specific columns, place them to the left of your start cell or use a range that deliberately excludes them.
Why does my imported data show fewer rows than my source?
The most common cause is a defined cell range that's too small. If you entered a range like `A1:D20` and your source has 50 rows, only 20 rows will be written. Switch to a single starting cell (e.g., `A1`) to let Coupler.io write all rows without a ceiling.
If you're not using a restricted range and data is still missing, check whether your source filters are narrowing the result set, or contact Coupler.io support with your data flow name.
Does Coupler.io support Google Sheets in shared drives (Team Drives)?
Yes, as long as the Google account connected to Coupler.io has Editor access to the shared drive spreadsheet. Make sure the account's permissions in the shared drive allow file editing, not just viewing.
Can I rename or reorder the columns that Coupler.io writes to my sheet?
Column names and order are determined by your source data and any transformations you apply in Coupler.io before the destination step. You can use the **Data set** step in the data flow setup wizard to filter, reorder, or rename columns before they reach Google Sheets.
What happens to my sheet if the data flow fails mid-run?
In Replace mode, Coupler.io performs the write as an atomic operation — if the run fails, the previous data remains in place and is not partially overwritten. In Append mode, any rows already written during the failed run may remain; check for duplicates if you retry.
Does my data flow break if I change the name of my destination file?
If you rename your Google Sheets file there is no need to reselect file in the Coupler destination, since the data flow does not break and will run like before.
Please note that it might take a while for the destination sheet to change it's name in Coupler's destination settings, however it will work as intended.
**Note:** Renaming a destination sheet does not update your data flow's destination settings. The data flow writes to the sheet name defined in the settings, not the sheet's current display name.
For example, if the destination is set to "Sheet 1" and you later rename that sheet to "Sheet 2," the data flow will create a new sheet named "Sheet 1" and write data there. To change the destination sheet, update the destination settings directly in Coupler.
Can I have Coupler.io send my data without a header?
At the moment, there isn’t an option to completely remove headers from being added during import. However, you can work around this depending on your import mode.
You can use append mode to add data to the bottom of the document. You will have to remove the header once and after that the data will be added without a header. You can learn about [append mode here](/functionality/preview-data/combining-data/append-data.md).
How do I turn the "Last updated column" on/off?
You can manage the "Last updated column" in the "Import mode" section of your "Destinations" tab in you data flow setup.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.coupler.io/destinations/categories/spreadsheets/google_sheets.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.