---
title: Upgrading to 2026-04
description: >
  This guide covers what's changed in `2026-04`, including the migration to
  `appMetafields` for reading metafields on order status targets, and how to
  adopt Polaris web components if you're upgrading from a version earlier than
  `2025-10`.
api_version: 2026-04
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/upgrading-to-2026-04
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/upgrading-to-2026-04.md
---

# Upgrading to 2026-04

This guide covers what's changed in `2026-04`, including the migration to `appMetafields` for reading metafields on order status targets, and how to adopt Polaris web components if you're upgrading from a version earlier than `2025-10`.

***

## Update API version

Set the API version to `2026-04` in `shopify.extension.toml`.

## shopify.extension.toml

```toml
api_version = "2026-04"


[[extensions]]
name = "your-extension"
handle = "your-extension"
type = "ui_extension"


# Contents of your existing file...
```

***

## File size limit

**Note:**

Your compiled UI extension bundle can't exceed 64 KB. Shopify enforces this limit at deployment to ensure fast loading times and optimal performance. Learn how to [analyze your bundle size](https://shopify.dev/docs/apps/build/app-extensions#analyzing-bundle-size).

***

## Migrate to order metafields

In `2026-04`, checkout metafields in the `metafields` API is replaced by order metafields in the [`appMetafields` API](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/target-apis/order-apis/metafields-api).

To set an order metafield during checkout, you must have an extension using a [pre-purchase Checkout UI extension target](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/extension-targets-overview#checkout-locations) and use the `applyMetafieldChange` Metafield API to write a cart metafield that has the [`cartToOrderCopyable` capability](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#cart-to-order-copyable). See [this guide](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/upgrading-to-2026-04#migrate-to-cart-metafields) for detailed instructions.

### Request metafields in your extension TOML

Request metafields that your extension needs access to in your extension configuration using `[[extensions.metafields]]`. See [configuration](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/configuration#metafields) for more details.

## shopify.extension.toml

```toml
[[extensions.metafields]]
namespace = "my-namespace"
key = "gift-requested"
```

### Update API calls

Instead of reading checkout metafields using the `shopify.metafields` API, use `shopify.appMetafields` to read order metafield values.

##### After: using appMetafields

##### Before: using metafields API (removed)

## Using appMetafields

```tsx
import "@shopify/ui-extensions/preact";
import { render } from "preact";


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


function Extension() {
  const giftRequested = shopify.appMetafields.value.find(
    (appMetafield) =>
      appMetafield.target.type === "order" &&
      appMetafield.metafield.namespace === "my-namespace" &&
      appMetafield.metafield.key === "gift-requested",
  );


  return (
    <s-text>
      Gift requested: {giftRequested?.metafield?.value === "true" ? "Yes" : "No"}
    </s-text>
  );
}
```

## Using metafields API (removed)

```tsx
import "@shopify/ui-extensions/preact";
import { render } from "preact";
import { useMetafield } from "@shopify/ui-extensions/customer-account/preact";


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


function Extension() {
  const giftRequested = useMetafield({
    namespace: "my-namespace",
    key: "gift-requested",
  });


  return (
    <s-text>
      Gift requested: {giftRequested?.value === "true" ? "Yes" : "No"}
    </s-text>
  );
}
```

***

## Adopting Polaris web components

The following sections apply if you're upgrading from a version earlier than `2025-10`. If you're already using Polaris web components, you can skip ahead.

### Adjust package dependencies

As of `2025-10`, Shopify recommends Preact for UI extensions. Update the dependencies in your `package.json` file and re-install.

##### New dependencies with Preact

##### Previous dependencies with React

##### Previous dependencies with JavaScript

## New dependencies with Preact

## package.json

```json
{
  "dependencies": {
    "preact": "^10.10.x",
    "@preact/signals": "^2.3.x",
    "@shopify/ui-extensions": "2026.4.x"
  }
}
```

## Previous dependencies with React

## package.json

```json
{
  "dependencies": {
    "react": "^18.0.0",
    "@shopify/ui-extensions": "2025.4.x",
    "@shopify/ui-extensions-react": "2025.4.x",
    "react-reconciler": "0.29.0"
  },
  "devDependencies": {
    "@types/react": "^18.0.0"
  }
}
```

## Previous dependencies with JavaScript

## package.json

```json
{
  "dependencies": {
    "@shopify/ui-extensions": "2025.4.x"
  }
}
```

### Type​Script configuration

Get full IntelliSense and auto-complete support by adding a config file for your extension at `extensions/{extension-name}/tsconfig.json`. You don't need to change your app's root `tsconfig.json` file.

##### New tsconfig.json

##### Old tsconfig.json

## New tsconfig.json

## tsconfig.json

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "preact",
    "target": "ES2020",
    "checkJs": true,
    "allowJs": true,
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}
```

## Old tsconfig.json

## tsconfig.json

```json
{
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["./src"]
}
```

### Upgrade the Shopify CLI

The new CLI adds support for building 2026-04 extensions.

The [`shopify app dev`](https://shopify.dev/docs/api/shopify-cli/app/app-dev) command runs your app and also generates a `shopify.d.ts` file in your extension directory, adding support for the new global `shopify` object.

## Support new global shopify object

## CLI

```bash
# Upgrade to latest version of the CLI
npm install -g @shopify/cli


# Run the app to generate the type definition file
shopify app dev
```

### Optional ESLint configuration

If your app is using ESLint, update your configuration to include the new global `shopify` object.

## .eslintrc.cjs

```js
module.exports = {
  globals: {
    shopify: 'readonly',
  },
};
```

### Migrate API calls

Instead of accessing APIs from a callback parameter or React hook, access them from the global `shopify` object. Here's an example of migrating the [Cart Line Target API](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/order-status/customer-account-order-status-cart-line-item-render-after) call.

##### New API calls in Preact

##### Previous API calls in React

##### Previous API calls in JavaScript

## New API calls in Preact

## Preact

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';


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


function Extension() {
  return (
    <s-text>Line item title: {shopify.target.value.merchandise.title}</s-text>
  );
}
```

## Previous API calls in React

## React

```tsx
import {
  reactExtension,
  Text,
  useCartLineTarget,
} from '@shopify/ui-extensions-react/customer-account';


export default reactExtension(
  'customer-account.order-status.cart-line-item.render-after',
  () => <Extension />,
);


function Extension() {
  const {
    merchandise: {title},
  } = useCartLineTarget();


  return <Text>Line item title: {title}</Text>;
}
```

## Previous API calls in JavaScript

## JavaScript

```tsx
import {extension} from '@shopify/ui-extensions/customer-account';


export default extension(
  'customer-account.order-status.cart-line-item.render-after',
  (root, {target}) => {
    const text = root.createText(`Line item title: ${target.current.title}`);
    root.appendChild(text);


    target.subscribe((updatedTarget) => {
      text.updateText(`Line item title: ${updatedTarget.title}`);
    });
  },
);
```

### Migrate to Polaris web components

Polaris web components are exposed as custom HTML elements. Update your React or JavaScript components to custom elements:

##### New components in Preact

##### Previous components in React

##### Previous components in JavaScript

## New components in Preact

## Preact

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';


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


function Extension() {
  return (
    <s-stack direction="inline" gap="base">
      <s-text-field label="Gift message"></s-text-field>
      <s-button variant="primary">Save</s-button>
    </s-stack>
  );
}
```

## Previous components in React

## React

```tsx
import {
  reactExtension,
  InlineStack,
  TextField,
  Button,
} from '@shopify/ui-extensions-react/customer-account';


export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);


function Extension() {
  return (
    <InlineStack>
      <TextField label="Gift message" />
      <Button>Save</Button>
    </InlineStack>
  );
}
```

## Previous components in JavaScript

## JavaScript

```tsx
import {
  extension,
  InlineStack,
  TextField,
  Button,
} from '@shopify/ui-extensions/customer-account';


export default extension(
  'customer-account.order-status.block.render',
  (root, _api) => {
    root.replaceChildren(
      root.createComponent(InlineStack, {}, [
        root.createComponent(TextField, {
          label: 'Gift message',
        }),
        root.createComponent(Button, {}, 'Save'),
      ]),
    );
  },
);
```

### Mapping legacy components to Polaris web

| **Legacy component** | **Polaris web component** | **Migration notes** |
| - | - | - |
| `Avatar` | [`Avatar`](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/web-components/media-and-visuals/avatar) | Available today |
| | [`Button group`](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/web-components/actions/button-group) | Available today |
| `Card` | [`Section`](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/web-components/layout-and-structure/section) | Available today |
| `CustomerAccountAction` | [`Customer account action`](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/web-components/actions/customer-account-action) | Available today |
| `ImageGroup` | [`Image group`](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/web-components/media-and-visuals/image-group) | Available today |
| `Menu` | [`Menu`](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/web-components/actions/menu) | Available today |
| `Page` | [`Page`](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/web-components/layout-and-structure/page) | Available today |
| `ResourceItem` | | Removed. Use [`Section`](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/web-components/layout-and-structure/section) instead. |

### Additional components

In addition to the components above, you can also use Polaris web components in the checkout library to build customer account UI extensions.

[More Polaris web components - Checkout components](https://shopify.dev/docs/api/checkout-ui-extensions/web-components)

***