Choose a version:

Storage API

The Storage API lets you persist key-value data scoped to the customer across sessions. Use this API to store customer preferences, dismissed states, or other lightweight data that should survive navigation and return visits.

Anchor to Use casesUse cases

Remember customer preferences: Save choices like preferred language, display options, or notification settings so they persist across visits.
Track dismissed content: Store whether a customer has dismissed a promotional banner or onboarding message so it doesn't reappear.
Cache lightweight data: Store small pieces of data to reduce redundant API calls, such as a customer's loyalty tier or last-viewed order.

Support

Targets (24)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides key-value storage scoped to the customer. Access the following properties on shopify to read, write, and delete persistent data across sessions.

Anchor to storage storage required: Key-value storage that persists across customer sessions for this extension target. Use this to store preferences, dismiss states, or cached data without requiring a backend call.

Storage

Key-value storage for a specific extension. Use storage to save preferences or cached data that should survive page reloads without requiring a backend call. Stored data is only available to this specific extension. The storage backend is implemented with `localStorage` and data persistence isn't guaranteed.

delete
Deletes a previously stored value by key.
```
(key: string) => Promise<void>
```
read
Read and return a stored value by key. The stored data is deserialized from JSON and returned as its original type. Returns the stored value for the given key, or `null` when no value exists. Doesn't throw on a missing key.
```
<T = unknown>(key: string) => Promise<T>
```
write
Write stored data for this key. The data must be serializable to JSON.
```
(key: string, data: any) => Promise<void>
```

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

import {useEffect, useState} from 'preact/hooks';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

const [preference, setPreference] =

useState(null);

useEffect(() => {

async function loadPreference() {

const stored =

await shopify.storage.read('locale_pref');

if (stored) {

setPreference(stored);

}

loadPreference();

}, []);

async function handleSave(value) {

await shopify.storage.write(

'locale_pref',

value,

);

setPreference(value);

}

return (

<s-stack direction="block" gap="base">

<s-text>

{preference

? `Saved preference: ${preference}`

: 'No preference saved'}

</s-text>

<s-button onClick={() => handleSave('en-US')}>

Set preference to en-US

</s-button>

</s-stack>

);

}

Examples

Description

Write a value to storage and read it back when the extension loads again. This example saves a locale preference using `shopify.storage.write()` and reads it when the extension loads with `shopify.storage.read()`.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useEffect, useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [preference, setPreference] =
    useState(null);

  useEffect(() => {
    async function loadPreference() {
      const stored =
        await shopify.storage.read('locale_pref');
      if (stored) {
        setPreference(stored);
      }
    }
    loadPreference();
  }, []);

  async function handleSave(value) {
    await shopify.storage.write(
      'locale_pref',
      value,
    );
    setPreference(value);
  }

  return (
    <s-stack direction="block" gap="base">
      <s-text>
        {preference
          ? `Saved preference: ${preference}`
          : 'No preference saved'}
      </s-text>
      <s-button onClick={() => handleSave('en-US')}>
        Set preference to en-US
      </s-button>
    </s-stack>
  );
}

Description

Remove a stored value when the customer resets a preference or state. This example tracks whether a promotion was dismissed and uses `shopify.storage.delete()` to clear the value when the customer wants to see it again.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useEffect, useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [dismissed, setDismissed] =
    useState(false);

  useEffect(() => {
    async function checkDismissed() {
      const value =
        await shopify.storage.read('promo_dismissed');
      if (value === 'true') {
        setDismissed(true);
      }
    }
    checkDismissed();
  }, []);

  async function handleDismiss() {
    await shopify.storage.write(
      'promo_dismissed',
      'true',
    );
    setDismissed(true);
  }

  async function handleReset() {
    await shopify.storage.delete(
      'promo_dismissed',
    );
    setDismissed(false);
  }

  if (dismissed) {
    return (
      <s-button onClick={handleReset}>
        Show promotion again
      </s-button>
    );
  }

  return (
    <s-stack direction="block" gap="base">
      <s-banner heading="Special offer!">
        Get 20% off your next order.
      </s-banner>
      <s-button onClick={handleDismiss}>
        Dismiss
      </s-button>
    </s-stack>
  );
}

Description

Check storage on load to decide whether to show a promotional banner. When the customer dismisses it, write to storage so it stays hidden on future visits.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useEffect, useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [dismissed, setDismissed] =
    useState(true);

  useEffect(() => {
    async function checkDismissed() {
      const value =
        await shopify.storage.read('promo_dismissed');
      setDismissed(value === 'true');
    }
    checkDismissed();
  }, []);

  async function handleDismiss() {
    await shopify.storage.write(
      'promo_dismissed',
      'true',
    );
    setDismissed(true);
  }

  if (dismissed) {
    return null;
  }

  return (
    <s-banner
      heading="Free shipping on your next order"
      onDismiss={handleDismiss}
    >
      <s-text>
        Use code FREESHIP at checkout.
      </s-text>
    </s-banner>
  );
}

Anchor to Best practicesBest practices

Store only small values: Keep stored data lightweight. Storage is intended for simple key-value pairs like preferences and flags, not large datasets.
Use descriptive keys: Name your storage keys clearly (for example, promo_dismissed or locale_pref) so their purpose is obvious and conflicts with other extensions are unlikely.
Handle missing values gracefully: Always check for null or undefined when reading from storage, since the value may not exist on the customer's first visit.
Don't store sensitive data: Storage isn't encrypted. Don't store personal information, tokens, or anything that could compromise customer privacy.

Anchor to LimitationsLimitations

Storage is scoped per customer and per extension. You can't share data between different extensions or access another customer's stored values.
On the pre-authenticated Order status page, storage is scoped to the customer associated with the order, not the browsing session.
All values are stored as strings. You must serialize and deserialize complex types (like JSON objects).

Was this page helpful?