Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the upgrade guide to upgrade your extension.

Storage API

The Storage API provides persistent local storage for POS UI extensions, allowing you to store, retrieve, and manage extension data that persists across user sessions, device restarts, and extension target state changes. Data is stored locally on the POS device in an isolated namespace specific to your extension.

The API supports key-value storage with automatic JSON serialization, type safety through TypeScript interfaces, and built-in error handling for storage constraint violations.

Anchor to Use casesUse cases

  • Data caching: Cache product information and pricing data to reduce API calls.
  • User preferences: Store user preferences like theme settings or workflow customizations.
  • Cross-target data: Pass contextual data between tile and action targets during multi-step workflows.
  • Session data: Maintain temporary session data that needs to survive navigation and cart changes.
Support
Targets (19)

Supported targets

Anchor to PropertiesProperties

The Storage API object provides persistent local storage for POS UI extensions. Access the following properties on the API object to store, retrieve, and manage extension data that persists across user sessions.

Anchor to clear
clear
() => Promise<void>
required

Clears all data from storage, removing all key-value pairs.

Anchor to delete
delete
<StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>(key: Keys) => Promise<boolean>
required

Deletes a specific key from storage and returns true if the key existed, false if it didn't exist. Returns false for non-existent keys rather than throwing an error. Commonly used for cleaning up temporary workflow data, removing expired cache entries, or handling user preference changes.

Anchor to entries
entries
<StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>() => Promise<[Keys, StorageTypes[Keys]][]>
required

Retrieves all stored key-value pairs as an array of tuples, preserving original data types. Returns all data at once which may impact memory usage with large datasets. Commonly used for debugging storage contents, implementing data export features, or performing bulk operations across stored data.

Anchor to get
get
<StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>(key: Keys) => Promise<StorageTypes[Keys]>
required

Retrieves the value associated with a key, returning undefined if the key doesn't exist. Always handle the undefined case by providing fallback values or conditional logic. Commonly used for loading user preferences, retrieving cached data, or accessing contextual information passed between extension targets.

Anchor to set
set
<StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>(key: Keys, value: StorageTypes[Keys]) => Promise<void>
required

Stores a value under the specified key, overwriting any existing value. Values must be JSON-serializable and return StorageError when storage limits are exceeded. Commonly used for storing user preferences, caching API responses, or passing contextual data from tiles to modals.

Examples
import React, {useState, useEffect} from 'react';
import {
Tile,
reactExtension,
useApi,
} from '@shopify/ui-extensions-react/point-of-sale';

const TileComponent = () => {
const api = useApi<'pos.home.tile.render'>();
const [itemCount, setItemCount] = useState(0);

useEffect(() => {
const initializeData = async () => {
const count = 10;
for (let i = 0; i < count; i++) {
await api.storage.set(`key-${i}`, `value-${i}`);
}
setItemCount(count);
};

initializeData();
}, [api.storage]);

return (
<Tile
title="Storage app"
subtitle="Clear example"
badgeValue={itemCount}
onPress={async () => {
await api.storage.clear();
api.toast.show('All data cleared');
setItemCount(0);
}}
enabled
/>
);
};

export default reactExtension('pos.home.tile.render', () => <TileComponent />);

Anchor to Best practicesBest practices

  • Validate retrieved data: Check data structure and types after calling get() since stored data may be outdated or corrupted. Provide sensible defaults and handle missing properties.
  • Plan for data evolution: Design your stored data structures to handle future changes. Include version fields in complex objects and implement migration logic to handle schema updates between extension versions.
  • Keep sensitive data out of local storage: Never store passwords, API keys, or other sensitive information. Use the Session API for secure backend communication and limit stored data to user preferences and non-sensitive workflow state.

Anchor to LimitationsLimitations

  • POS UI extensions can store up to a maximum of 100 entries.
  • The maximum key size is ~1 KB and the maximum value size is ~1 MB.
  • Data persists even when extension targets are disabled or removed.
  • Stored extension data is automatically cleared after 30 days of inactivity. The inactivity timer is reset only by write operations (set); read operations (get) do not affect the timer.
Was this page helpful?