Deprecate useLocalizationMarket and localization.market across surfaces

.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.

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<Market | undefined>;
 }

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<

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<Market | undefined>;
 }

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,