What is PropertiesService in Google Sheets Apps Script?
PropertiesService stores small key-value strings that persist between script runs. Use it for API tokens, last sync timestamps, feature flags, or webhook secrets instead of hiding values in cells. Script, user, and document property stores each serve different sharing and scope needs in a spreadsheet project.
When to use it
Use PropertiesService when scripts need memory across runs: remember the last processed row ID, store a shared API key for triggers, or save per-user preferences in a multi-user tool.
When to skip it
Skip PropertiesService for large data tables or anything users should audit in the grid. Use a Settings tab or a database when values belong in the sheet or need bulk editing.
How it works
-
1
Call PropertiesService.getScriptProperties() for project-wide keys shared by all users and triggers.
-
2
Use getUserProperties() for per-user values when someone runs a custom menu tool.
-
3
Use getDocumentProperties() for values tied to this spreadsheet file only.
-
4
Set with setProperty('key', 'value') and read with getProperty('key').
-
5
Delete stale keys with deleteProperty when rotating tokens.
-
6
Never log secret values to Executions or a public Debug tab.
Examples in Google Sheets
API token storage
A setup function prompts once for a token, saves it in Script Properties, and nightly UrlFetchApp reads it without a visible cell on the sheet.
Last sync cursor
After each import, setProperty('lastRow', String(lastRow)) so the next trigger only processes new rows.
Per-user column choice
A sidebar saves the user's preferred status filter in User Properties and restores it on next open.
Better Sheets resources
Common mistakes
-
Storing secrets in sheet cells or comments where any editor can read them.
-
Using Script Properties for per-user prefs that overwrite each other across teammates.
-
Forgetting PropertiesService only stores strings; JSON.stringify objects before save.
-
Hitting the roughly 500 KB total limit per store with large blobs.
-
Deleting all properties during debug and losing production tokens.
Frequently asked questions
- What is the difference between script and document properties?
- Script properties belong to the Apps Script project. Document properties belong to the spreadsheet file. User properties belong to each Google account.
- Can editors see Script Properties?
- Anyone with script edit access can read them in code or the legacy script properties UI. Treat them as hidden from casual users, not encrypted secrets.
- How do I set a property in code?
- PropertiesService.getScriptProperties().setProperty('apiKey', 'abc123').
- Can triggers read properties?
- Yes. Time-driven and installable triggers use Script Properties freely after the project is authorized.
- How do I list all keys?
- getProperties() returns an object of all key-value pairs in that store. Use sparingly in production logs.
- Are properties backed up when I copy the sheet?
- Document properties copy with the file. Script properties behavior depends on whether the script container copies; verify after duplicate.
- Can I store numbers?
- Store as strings and parseInt or parseFloat on read. There is no native number type.
- What is PropertyStore?
- It is the interface returned by getScriptProperties and siblings. Methods are the same across stores.
Related Tutorials
Watch how PropertiesService works
Convert Google Sheets into a REST API
Scrape Google Maps
Related blog posts
Guides that explain PropertiesService in more depth.
How to reference a different Google Spreadsheet in Apps Script?
Transferring Data Between Cells in Different Spreadsheets
Read post →What's Better Than Google Sheets?
Nothing is better than Google Sheets. You just need to learn more about the unlimited power of Google Sheets. Functions, Formulas, Apps Script and more.
Read post →Get Sheet Done: Start Your Business in Sheets
4 Ways Google Sheets Can Help You Start Up Create a list Curate Links Track Something Write Code
Read post →Related terms
Script Editor
The Script Editor is the Apps Script workspace inside your spreadsheet where you write JavaScript that talks to Sheets, Gmail, and other Google services. You open it from Extensions > Apps Script. Every function you save can be run manually, bound to a trigger, or linked from a custom menu.
Read guide →Apps Script triggers
Triggers tell Apps Script when to run a function: on edit, on open, on a schedule, or when a form is submitted. Simple triggers use reserved names like onEdit. Installable triggers are created in the Apps Script Triggers page and can do more, including running as a specific user or on a timer.
Read guide →Google Sheets API
The Google Sheets API lets other programs read and update spreadsheets over HTTP using JSON. It is how dashboards, backends, and mobile apps sync data without opening the Google Sheets UI. Apps Script inside a file is simpler for sheet owners; the API fits systems built in Python, Node, or other stacks.
Read guide →Google Sheets automation
Automation means work happens without repeating the same clicks every day: imports update, emails send, rows move, and dashboards refresh. In Sheets, automation usually stacks built-in features, Apps Script, and sometimes the Sheets API or add-ons. Start with the lightest tool that still solves the job.
Read guide →Done reading about PropertiesService?
Membership unlocks 600+ tutorials, unlimited generators, and every template. Practical lessons. Zero fluff.
Need this once
Jump to a free tool or a single tutorial for this topic.
Learning Sheets for real
Unlock the full library, generators, and templates with membership.