Choose a version:

Storage API

The Storage API provides key-value storage that persists across page loads within the current checkout session. Use this API to save and restore extension state, such as dismissed banners, form progress, or buyer preferences, so that the buyer doesn't lose context when navigating between checkout steps.

Storage is scoped to your extension. Other extensions can't read or write your stored data.

Anchor to Use casesUse cases

Persist dismissed banners: Save whether the buyer has dismissed a promotional banner so it stays hidden when they navigate back.
Restore form state: Store partially completed form data so that the buyer doesn't have to re-enter it after navigating away and returning.
Track extension state: Save flags or counters that your extension needs to maintain across page loads within the checkout.

Support

Targets (33)

Supported targets

Anchor to Properties and methodsProperties and methods

The shopify global object provides session storage for the current checkout. Access the following properties and methods on shopify to read, write, and delete stored values. Available to purchase extension targets.

Anchor to storage storage required: Key-value storage that persists across page loads within the current checkout session. Data is shared across all activated targets associated with this extension.

Caution
Data persistence isn't guaranteed and storage is cleared when the buyer starts a new checkout.
Caution: Data persistence isn't guaranteed and storage is cleared when the buyer starts a new checkout.

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 function extension() {

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

}

function Extension() {

const {storage} = shopify;

const [tosConsent, setTosConsent] =

useState(false);

useEffect(() => {

async function readFromStorage() {

const tosConsent = await storage.read(

'tos-consent',

);

setTosConsent(Boolean(tosConsent));

}

readFromStorage();

}, [storage]);

async function cacheConsent(value) {

setTosConsent(value);

await storage.write('tos-consent', value);

}

return (

<s-checkbox

checked={tosConsent}

onChange={() => cacheConsent(!tosConsent)}

label="I agree with the terms of service"

);

}

Examples

Description

Save and restore a checkbox state so the buyer doesn't need to re-check it after navigating. This example stores a terms-of-service consent value with `shopify.storage` and reads it back on mount.

jsx

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

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

function Extension() {
  const {storage} = shopify;
  const [tosConsent, setTosConsent] =
    useState(false);

  useEffect(() => {
    async function readFromStorage() {
      const tosConsent = await storage.read(
        'tos-consent',
      );

      setTosConsent(Boolean(tosConsent));
    }

    readFromStorage();
  }, [storage]);

  async function cacheConsent(value) {
    setTosConsent(value);
    await storage.write('tos-consent', value);
  }

  return (
    <s-checkbox
      checked={tosConsent}
      onChange={() => cacheConsent(!tosConsent)}
      label="I agree with the terms of service"
    />
  );
}

Description

Remove a previously stored value from session storage. This example renders a dismissible promotion banner that persists with `write()` and clears with `delete()`, letting the buyer reset the dismissed state.

jsx

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

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

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

  useEffect(() => {
    async function checkDismissed() {
      const value =
        await storage.read('promo-dismissed');
      setDismissed(Boolean(value));
    }

    checkDismissed();
  }, [storage]);

  async function dismiss() {
    setDismissed(true);
    await storage.write(
      'promo-dismissed',
      true,
    );
  }

  async function reset() {
    setDismissed(false);
    await storage.delete('promo-dismissed');
  }

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

  return (
    <s-banner
      heading="Limited offer"
      dismissible
      onDismiss={dismiss}
    >
      Use code SAVE20 for 20% off today.
    </s-banner>
  );
}

Anchor to Best practicesBest practices

Store only small, serializable values: Storage uses localStorage under the hood. Keep stored data small and JSON-serializable to avoid unexpected behavior.
Use delete() instead of writing empty values: To remove a stored entry, call storage.delete(key) rather than writing null or an empty string. This keeps your storage clean and avoids ambiguity when checking for missing keys.

Anchor to LimitationsLimitations

Stored data persists only for the current checkout session. After checkout completes or the session expires, all stored values are cleared. Data persistence within a session isn't guaranteed, so don't rely on storage for critical checkout states.

Was this page helpful?