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 migration guide to upgrade your extension.

Choose a version:

Storage API

The API for interacting with local storage.

Anchor to StandardApiStandardApi

The base API object provided to purchase extension targets.

Anchor to storage storage required: The key-value storage for the extension.

It uses localStorage and should persist across the customer's current checkout session.

Caution
Data persistence isn't guaranteed and storage is reset when the customer starts a new checkout.
Caution: Data persistence isn't guaranteed and storage is reset when the customer starts a new checkout.
Data is shared across all activated targets associated with this extension.

Storage

A key-value storage object for the extension. Stored data is only available to this specific extension and any of its instances. The storage backend is implemented with `localStorage` and should persist across the buyer's checkout session. However, data persistence isn't guaranteed.

delete
Delete stored data 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 primitive. Returns `null` if no stored data exists.
```
<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>
```

Anchor to useStorage
useStorage()

Returns the key-value Storage interface for the extension. Uses localStorage and should persist across the buyer's current checkout session. However, data persistence isn't guaranteed and storage is reset when the buyer starts a new checkout.

Data is shared across all activated extension targets of this extension. In versions <=2023-07, each activated extension target had its own storage.

Anchor to useStorage-returnsReturns

Examples

React

import {useEffect, useState} from 'react';

import {

reactExtension,

Checkbox,

useApi,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.block.render',

() => <Extension />,

);

function Extension() {

const {storage} = useApi();

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: boolean) {

setTosConsent(value);

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

}

return (

<Checkbox

id="tos"

name="tos"

onChange={cacheConsent}

checked={tosConsent}

I agree with the terms of service

</Checkbox>

);

}

Examples

React

import {useEffect, useState} from 'react';
import {
  reactExtension,
  Checkbox,
  useApi,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const {storage} = useApi();
  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: boolean) {
    setTosConsent(value);
    await storage.write('tos-consent', value);
  }

  return (
    <Checkbox
      id="tos"
      name="tos"
      onChange={cacheConsent}
      checked={tosConsent}
    >
      I agree with the terms of service
    </Checkbox>
  );
}