From e4768fef3efc4139e9a55091ce1c58813b3f8592 Mon Sep 17 00:00:00 2001 From: Raymond Zeng Date: Wed, 12 Aug 2026 11:30:32 -0400 Subject: [PATCH] Deprecate `useLocalizationMarket` and `localization.market` across surfaces Add `@deprecated` tag and `> Caution:` doc block to the `useLocalizationMarket` hook and `localization.market` property on both the checkout and customer-account surfaces. The shopify.dev migration guide already lists these as deprecated, but the source types had no deprecation annotation (hooks) or were missing the Caution block needed for docs rendering (property). Co-Authored-By: Claude Opus 4.6 --- .changeset/deprecate-localization-market.md | 5 +++++ .../src/surfaces/checkout/api/standard/standard.ts | 13 ++++++++----- .../src/surfaces/checkout/preact/market.ts | 10 ++++++++-- .../api/order-status/order-status.ts | 7 ++++++- .../src/surfaces/customer-account/preact/market.ts | 10 ++++++++-- 5 files changed, 35 insertions(+), 10 deletions(-) create mode 100644 .changeset/deprecate-localization-market.md diff --git a/.changeset/deprecate-localization-market.md b/.changeset/deprecate-localization-market.md new file mode 100644 index 0000000000..bb7b51c894 --- /dev/null +++ b/.changeset/deprecate-localization-market.md @@ -0,0 +1,5 @@ +--- +'@shopify/ui-extensions': patch +--- + +Deprecate `useLocalizationMarket` and `localization.market` on both checkout and customer-account surfaces. These will be removed in a future version of the API. diff --git a/packages/ui-extensions/src/surfaces/checkout/api/standard/standard.ts b/packages/ui-extensions/src/surfaces/checkout/api/standard/standard.ts index bf4875aefd..06d3859e42 100644 --- a/packages/ui-extensions/src/surfaces/checkout/api/standard/standard.ts +++ b/packages/ui-extensions/src/surfaces/checkout/api/standard/standard.ts @@ -436,12 +436,15 @@ export interface Localization { /** * The [market](/docs/apps/build/markets) context of the checkout, * carried over from the cart context. Markets group countries and - * regions with shared pricing, languages, and domains. The market - * context updates when the buyer changes the country of their - * shipping address. The value is `undefined` if the market is unknown. + * regions with shared pricing, languages, and domains. In cases where + * multiple markets match, this returns the most narrowly scoped + * country region market. The market context updates when the buyer + * changes the country of their shipping address. The value is + * `undefined` if the market is unknown. * - * @deprecated Merchants now manage which extensions load for each - * market, so extensions no longer need to check this value. + * > Caution: This `market` field is deprecated and will be removed in a future version of the API. + * + * @deprecated This `market` field will be removed in a future version of the API. */ market: SubscribableSignalLike; } diff --git a/packages/ui-extensions/src/surfaces/checkout/preact/market.ts b/packages/ui-extensions/src/surfaces/checkout/preact/market.ts index ecdb075a91..e15032c357 100644 --- a/packages/ui-extensions/src/surfaces/checkout/preact/market.ts +++ b/packages/ui-extensions/src/surfaces/checkout/preact/market.ts @@ -5,8 +5,14 @@ import {useApi} from './api'; import {useSubscription} from './subscription'; /** - * Returns the market of the checkout, and automatically re-renders - * your component if it changes. + * Returns the market of the checkout, carried over from the cart context. + * In cases where multiple markets match, this returns the most narrowly + * scoped country region market. Automatically re-renders your component + * if it changes. + * + * > Caution: This hook is deprecated and will be removed in a future version of the API. + * + * @deprecated This hook will be removed in a future version of the API. * @publicDocs */ export function useLocalizationMarket< diff --git a/packages/ui-extensions/src/surfaces/customer-account/api/order-status/order-status.ts b/packages/ui-extensions/src/surfaces/customer-account/api/order-status/order-status.ts index fbc1e6028f..c5448a692c 100644 --- a/packages/ui-extensions/src/surfaces/customer-account/api/order-status/order-status.ts +++ b/packages/ui-extensions/src/surfaces/customer-account/api/order-status/order-status.ts @@ -201,7 +201,12 @@ export interface OrderStatusLocalization { /** * The [market](/docs/apps/build/markets) associated with the order, carried * over from the cart context. Markets group countries and regions with shared pricing, - * languages, and domains. The value is `undefined` if the market is unknown. + * languages, and domains. In cases where multiple markets match, this returns the most + * narrowly scoped country region market. The value is `undefined` if the market is unknown. + * + * > Caution: This `market` field is deprecated and will be removed in a future version of the API. + * + * @deprecated This `market` field will be removed in a future version of the API. */ market: SubscribableSignalLike; } diff --git a/packages/ui-extensions/src/surfaces/customer-account/preact/market.ts b/packages/ui-extensions/src/surfaces/customer-account/preact/market.ts index 6aa04b137b..49b5dc7e0d 100644 --- a/packages/ui-extensions/src/surfaces/customer-account/preact/market.ts +++ b/packages/ui-extensions/src/surfaces/customer-account/preact/market.ts @@ -6,8 +6,14 @@ import {useSubscription} from './subscription'; import {ExtensionHasNoFieldError} from './errors'; /** - * Returns the market of the checkout, and automatically re-renders - * your component if it changes. + * Returns the market associated with the order, carried over from the cart + * context. In cases where multiple markets match, this returns the most + * narrowly scoped country region market. Automatically re-renders your + * component if it changes. + * + * > Caution: This hook is deprecated and will be removed in a future version of the API. + * + * @deprecated This hook will be removed in a future version of the API. */ export function useLocalizationMarket< Target extends RenderOrderStatusExtensionTarget = RenderOrderStatusExtensionTarget,