Skip to main content

Upgrade to the latest API version and Polaris web components

This guide explains the steps you need to take to migrate your customer account UI extensions to the latest API version, including the removal of checkout metafield write types.

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 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: Migrate to order metafieldsStep 2: Migrate 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 Migrate API callsMigrate API calls

Instead of accessing APIs from a callback parameter, access them from the global shopify object. Here's an example of migrating 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 Migrate to web componentsMigrate 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 componentMigration guide
AvatarMigrate Avatar
BadgeMigrate Badge
BannerMigrate Banner
BlockLayoutMigrate BlockLayout
BlockSpacerMigrate BlockSpacer
BlockStackMigrate BlockStack
ButtonMigrate Button
CardMigrate Card
CheckboxMigrate Checkbox
ChoiceMigrate Choice
ChoiceListMigrate ChoiceList
ClipboardItemMigrate ClipboardItem
ConsentCheckboxMigrate ConsentCheckbox
ConsentPhoneFieldMigrate ConsentPhoneField
CustomerAccountActionMigrate CustomerAccountAction
DateFieldMigrate DateField
DatePickerMigrate DatePicker
DisclosureMigrate Disclosure
DividerMigrate Divider
DropZoneMigrate DropZone
FormMigrate Form
GridMigrate Grid
GridItemMigrate GridItem
HeadingMigrate Heading
HeadingGroupMigrate HeadingGroup
IconMigrate Icon
ImageMigrate Image
ImageGroupMigrate ImageGroup
InlineLayoutMigrate InlineLayout
InlineSpacerMigrate InlineSpacer
InlineStackMigrate InlineStack
LinkMigrate Link
ListMigrate List
ListItemMigrate List
MapMigrate Map
MapMarkerMigrate MapMarker
MapPopoverMigrate MapPopover
MenuMigrate Menu
ModalMigrate Modal
PageMigrate Page
PaymentIconMigrate PaymentIcon
PhoneFieldMigrate PhoneField
PopoverMigrate Popover
PressableMigrate Pressable
ProductThumbnailMigrate ProductThumbnail
QRCodeMigrate QRCode
ResourceItemMigrate ResourceItem
ScrollViewMigrate ScrollView
SelectMigrate Select
SheetMigrate Sheet
SkeletonImageMigrate SkeletonImage
SkeletonTextMigrate SkeletonText
SkeletonTextBlockMigrate SkeletonTextBlock
SpinnerMigrate Spinner
StepperMigrate Stepper
Style helperMigrate Style helper
SwitchMigrate Switch
TagMigrate Tag
TextMigrate Text
TextBlockMigrate TextBlock
TextFieldMigrate TextField
ToggleButtonMigrate ToggleButton
ToggleButtonGroupMigrate ToggleButtonGroup
TooltipMigrate Tooltip
ViewMigrate View
Was this page helpful?