Skip to main content

Upgrade to the latest API version and Polaris web components

This guide explains the steps you need to take to upgrade your customer account UI extensions to the latest API version, including the upgrade to reading order metafields with the appMetafields API.

Info

If you're upgrading from a version earlier than 2025-10, you'll need to adopt Polaris web components. Versions 2025-10 and later use web components by default.

Anchor to Upgrade using AIUpgrade using AI

Upgrade your extensions faster by using Shopify's AI Toolkit to automate the bulk of the work:

  1. Follow the instructions to install the Shopify AI Toolkit.

  2. Ask your preferred AI coding agent to upgrade your extension using the Shopify AI Toolkit with a prompt such as: “Use the shopify polaris customer account extensions skill to upgrade the extensions/$extensionFolder extension to version 2026-04”.

    Info

    This process can take several minutes, depending on the size of your extension.

  3. Review changes made by your agent before you publish your new extension version:

    • Use the upgrade guide on this page to be sure your agent covered everything.
    • Run your extension locally to properly test the upgraded output and identify any gaps.

Anchor to Step 1: Update API versionStep 1: Update API version

Update the API version to the latest version in shopify.extension.toml (for example, 2026-04).

shopify.extension.toml

api_version = "2026-04"

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

# Contents of your existing file...

Anchor to Step 2: Upgrade to order metafieldsStep 2: Upgrade to order metafields

In 2026-04, checkout metafields in the metafields API is replaced by order metafields in the appMetafields API.

To set an order metafield during checkout, you must have an extension using a pre-purchase Checkout UI extension target and use the applyMetafieldChange Metafield API to write a cart metafield that has the cart_to_order_copyable capability. See this guide for detailed instructions.

Anchor to Request metafields in your extension TOMLRequest metafields in your extension TOML

Request metafields that your extension needs access to in your extension configuration using [[extensions.metafields]]. See configuration for more details.

shopify.extension.toml

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

Anchor to Update API callsUpdate API calls

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

package.json

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>
);
}

Anchor to Step 3: Adopt web components and PreactStep 3: Adopt web components and Preact

The following sections apply if you're upgrading from a version earlier than 2025-10. If you're already using web components and Preact, you don't need to make any changes.

Anchor to Adjust package dependenciesAdjust package dependencies

For API versions 2025-10 and later, Shopify recommends Preact for UI extensions. Update the dependencies in your package.json file and re-install.

package.json

New dependencies with Preact

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

Anchor to TypeScript configurationTypeScript 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.

tsconfig.json

New tsconfig.json

{
"compilerOptions": {
"jsx": "react-jsx",
"jsxImportSource": "preact",
"target": "ES2020",
"checkJs": true,
"allowJs": true,
"moduleResolution": "node",
"esModuleInterop": true
},
"include": ["./src", "./shopify.d.ts"]
}

Anchor to Upgrade the Shopify CLIUpgrade the Shopify CLI

The new CLI adds support for building with web components.

The shopify 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

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

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

Anchor to Optional ESLint configurationOptional ESLint configuration

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

.eslintrc.cjs

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

Anchor to Upgrade API callsUpgrade API calls

Instead of accessing APIs from a callback parameter, access them from the global shopify object. Here's an example of upgrading the Cart Line Target API call.

Preact

New API calls in Preact

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>
);
}

Anchor to Upgrade to web componentsUpgrade to web components

Web components are exposed as custom HTML elements. Update your React or JavaScript components to custom elements.

Preact

New components in Preact

/* eslint-disable react/self-closing-comp */
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>
);
}

Anchor to Mapping legacy components to web componentsMapping legacy components to web components

Legacy componentUpgrade guide
AvatarUpgrade Avatar
BadgeUpgrade Badge
BannerUpgrade Banner
BlockLayoutUpgrade BlockLayout
BlockSpacerUpgrade BlockSpacer
BlockStackUpgrade BlockStack
ButtonUpgrade Button
CardUpgrade Card
CheckboxUpgrade Checkbox
ChoiceUpgrade Choice
ChoiceListUpgrade ChoiceList
ClipboardItemUpgrade ClipboardItem
CustomerAccountActionUpgrade CustomerAccountAction
DateFieldUpgrade DateField
DatePickerUpgrade DatePicker
DisclosureUpgrade Disclosure
DividerUpgrade Divider
DropZoneUpgrade DropZone
FormUpgrade Form
GridUpgrade Grid
GridItemUpgrade GridItem
HeadingUpgrade Heading
HeadingGroupUpgrade HeadingGroup
IconUpgrade Icon
ImageUpgrade Image
ImageGroupUpgrade ImageGroup
InlineLayoutUpgrade InlineLayout
InlineSpacerUpgrade InlineSpacer
InlineStackUpgrade InlineStack
LinkUpgrade Link
ListUpgrade List
ListItemUpgrade List
MapUpgrade Map
MapMarkerUpgrade MapMarker
MapPopoverUpgrade MapPopover
MenuUpgrade Menu
ModalUpgrade Modal
PageUpgrade Page
PaymentIconUpgrade PaymentIcon
PhoneFieldUpgrade PhoneField
PopoverUpgrade Popover
PressableUpgrade Pressable
ProductThumbnailUpgrade ProductThumbnail
QRCodeUpgrade QRCode
ResourceItemUpgrade ResourceItem
ScrollViewUpgrade ScrollView
SelectUpgrade Select
SheetUpgrade Sheet
SkeletonImageUpgrade SkeletonImage
SkeletonTextUpgrade SkeletonText
SkeletonTextBlockUpgrade SkeletonTextBlock
SpinnerUpgrade Spinner
StepperUpgrade Stepper
Style helperUpgrade Style helper
SwitchUpgrade Switch
TagUpgrade Tag
TextUpgrade Text
TextBlockUpgrade TextBlock
TextFieldUpgrade TextField
ToggleButtonUpgrade ToggleButton
ToggleButtonGroupUpgrade ToggleButtonGroup
TooltipUpgrade Tooltip
ViewUpgrade View
Was this page helpful?