Apps Script Properties Service Guide: Store and Manage Data in Google Apps Script

When building automations with Google Apps Script, there are many situations where you need to store information that persists between script executions. For example, you may want to save API keys, user preferences, configuration settings, timestamps, counters, or application state.

Many beginners store this information directly in spreadsheets, but this approach isn't always secure or efficient. Fortunately, Google Apps Script provides a built-in solution called the Properties Service.

The Properties Service allows developers to store key-value pairs that remain available even after a script finishes running. It acts as a lightweight storage system for your Apps Script projects and is commonly used for configuration management, authentication credentials, application settings, and workflow tracking.

In this comprehensive guide, you'll learn everything about the Google Apps Script Properties Service, including its types, methods, use cases, best practices, limitations, and real-world examples.

What Is the Apps Script Properties Service?

The Properties Service is a built-in Google Apps Script service that stores persistent data as key-value pairs. Think of it as a simple database where each value has a unique key, data remains available between script executions, and information can be retrieved, updated, or deleted.

For example, a key called API_KEY might store the value 123456789. The script can retrieve this value anytime in the future.

Why Use Properties Service?

Many automation projects require persistent storage — for example, saving API credentials, storing user settings, tracking workflow progress, saving timestamps, recording execution history, and managing application configuration. Instead of hardcoding values inside scripts, developers can store them securely using Properties Service.

Benefits of Properties Service

• Persistent Data Storage: Data remains available after script execution ends.
• Easy to Use: Simple methods for storing and retrieving values.
• Lightweight Solution: No need for external databases.
• Secure Configuration Management: Store configuration settings separately from code.
• Supports Automation Workflows: Track progress across multiple executions.

Types of Properties in Apps Script

Google Apps Script provides three property stores, each serving a different purpose.

Script Properties

Script Properties are shared by all users of a script and are accessible by the script owner and authorized users. Best used for API keys, global configuration settings, and shared application settings.

PropertiesService.getScriptProperties();

User Properties

User Properties are unique to each user — each user gets their own storage. Best used for personal preferences, user-specific settings, and individual workflow data.

PropertiesService.getUserProperties();

Document Properties

Document Properties are attached to a specific Google document and accessible by users of that document. Best used for document settings, add-on configurations, and shared document metadata.

PropertiesService.getDocumentProperties();

Understanding Key-Value Storage

Properties Service stores data as strings. For example, a key called theme might hold the value dark. All stored values are converted to strings automatically.

Accessing Script Properties

First, obtain the property store:

const props = PropertiesService.getScriptProperties();

Now the script can create, read, update, and delete properties.

Storing a Property

Use setProperty() to save a value:

function saveAPIKey() {
  const props = PropertiesService.getScriptProperties();
  props.setProperty("API_KEY", "123456789");
}

Retrieving a Property

Use getProperty() to read a value:

function getAPIKey() {
  const props = PropertiesService.getScriptProperties();
  const apiKey = props.getProperty("API_KEY");
  Logger.log(apiKey);
}

// Output: 123456789

Updating Properties

Simply call setProperty() again — the previous value is replaced:

props.setProperty("API_KEY", "NEW_KEY");

Deleting a Property

Use deleteProperty() to permanently remove a value:

props.deleteProperty("API_KEY");

Storing and Retrieving Multiple Properties

You can save multiple values at once, which is more efficient than multiple individual calls:

props.setProperties({
  API_KEY: "12345",
  REGION: "US",
  VERSION: "1.0"
});

Retrieve them all at once with getProperties():

const data = props.getProperties();

// Returns:
// {
//   API_KEY: "12345",
//   REGION: "US",
//   VERSION: "1.0"
// }

This is useful for configuration loading.

Working with User Properties

User Properties store individual user settings, so different users can have different preferences:

function saveTheme() {
  const userProps = PropertiesService.getUserProperties();
  userProps.setProperty("theme", "dark");
}

Working with Document Properties

Document Properties are useful when creating add-ons, for storing document preferences, workflow settings, and shared metadata:

const docProps = PropertiesService.getDocumentProperties();

Storing and Retrieving JSON Objects

Properties only store strings, so complex data should be converted to JSON before saving:

const settings = {
  theme: "dark",
  language: "English"
};

props.setProperty("settings", JSON.stringify(settings));

To retrieve it, parse the string back into a usable object:

const settings = JSON.parse(props.getProperty("settings"));

Real-World Examples

Storing API Keys Securely

Many Apps Script projects connect to external APIs. Hardcoding a key directly in your code is a bad practice since anyone viewing the script can see it:

// Bad practice
const API_KEY = "123456789";

A better approach is to store it in Properties Service and retrieve it only when needed:

props.setProperty("API_KEY", "123456789");

This improves security and maintainability.

Workflow Tracking

Suppose a script processes 10,000 records. Store the progress so execution can resume later if it stops:

props.setProperty("LAST_ROW", "5000");

Scheduled Reports

Store the last report date so future executions can determine whether a report needs updating:

props.setProperty("LAST_REPORT", "2026-06-01");

Using Properties Service with Triggers

Properties Service works well with time-driven triggers. A typical workflow: daily trigger runs → checks last execution date → generates report → updates property. This prevents duplicate processing.

Creating Configuration Files

Properties Service can act as a lightweight configuration system for storing API URLs, feature flags, environment settings, and notification preferences:

props.setProperties({
  ENV: "Production",
  VERSION: "2.0",
  REGION: "US"
});

Best Practices

• Use Meaningful Keys: Use LAST_REPORT_DATE instead of vague keys like A.
• Store Sensitive Information Carefully: Properties Service is better than hardcoding secrets, but always restrict script access appropriately.
• Use JSON for Complex Data: Store objects with JSON.stringify() and retrieve them with JSON.parse().
• Remove Unused Properties: Regularly clean old values.
• Separate Configuration from Logic: Keep settings inside Properties Service and business logic inside scripts.

Common Mistakes

• Forgetting Values Are Strings: A stored value of 100 is retrieved as the string "100" — convert it using Number(value) when necessary.
• Overusing Properties Service: It is not a replacement for large databases — use spreadsheets or databases for large datasets.
• Poor Naming Conventions: Always use descriptive keys.

Limitations of Properties Service

• Storage Quotas: Google imposes limits on the number of properties and total storage size.
• String Storage Only: All values are stored as text.
• Not Suitable for Large Datasets: Properties Service is designed for configuration and metadata, not for storing thousands of records.

Properties Service vs Spreadsheet Storage

Advanced Use Cases

Organizations use Properties Service for API authentication (storing tokens securely), application settings (global configurations), user preferences (personalized experiences), workflow state tracking (automation progress), and add-on development (document-specific settings).

Common Business Applications

Businesses use Properties Service when building attendance systems, CRM automations, reporting dashboards, invoice generators, workflow engines, email automation systems, and API integrations.