[checkout] Add cart instructions API

.changeset/heavy-adults-joke.md

@@ -0,0 +1,8 @@
+---
+'@shopify/ui-extensions-react': minor
+'@shopify/ui-extensions': minor
+---
+
+Added `CartInstructions` (accessed using `api.instructions`) to checkout. These represent the cart instructions used to create the checkout and possibly limit extension capabilities. These instructions should be checked prior to performing any actions that may be affected by them.
+
+For example, if you intend to add a discount code via the `applyDiscountCodeChange` method, check `api.instructions.discounts.canUpdateDiscountCodes` to ensure it's supported in this checkout.

packages/ui-extensions-react/src/surfaces/checkout.ts

@@ -348,3 +348,4 @@ export {useDeliveryGroupListTarget} from './checkout/hooks/delivery-group-list-t
 export {useDeliverySelectionGroups} from './checkout/hooks/delivery-selection-groups';
 export {useCheckoutToken} from './checkout/hooks/checkout-token';
 export {useCustomerPrivacy} from './checkout/hooks/customer-privacy';
+export {useInstructions} from './checkout/hooks/instructions';

packages/ui-extensions-react/src/surfaces/checkout/hooks/instructions.ts

@@ -0,0 +1,16 @@
+import type {
+  CartInstructions,
+  RenderExtensionTarget,
+} from '@shopify/ui-extensions/checkout';
+
+import {useApi} from './api';
+import {useSubscription} from './subscription';
+
+/**
+ * Returns the cart instructions used to create the checkout and possibly limit extension capabilities.
+ */
+export function useInstructions<
+  Target extends RenderExtensionTarget = RenderExtensionTarget,
+>(): CartInstructions {
+  return useSubscription(useApi<Target>().instructions);
+}

packages/ui-extensions/src/shared.ts

@@ -21,6 +21,7 @@ export type ApiVersion =
   | '2023-10'
   | '2024-01'
   | '2024-04'
+  | '2024-07'
   | 'unstable';
 
 /**
@@ -865,6 +866,7 @@ export type StorefrontApiVersion =
   | '2023-07'
   | '2024-01'
   | '2024-04'
+  | '2024-07'
   | 'unstable';
 
 /**

packages/ui-extensions/src/surfaces/checkout.ts

@@ -68,6 +68,13 @@ export type {
   VisitorError,
   VisitorSuccess,
   VisitorResult,
+  CartInstructions,
+  AttributesCartInstructions,
+  DeliveryCartInstructions,
+  DiscountsCartInstructions,
+  CartLinesCartInstructions,
+  MetafieldsCartInstructions,
+  NotesCartInstructions,
 } from './checkout/api/standard/standard';
 
 export type {

packages/ui-extensions/src/surfaces/checkout/api/shared.ts

@@ -138,5 +138,8 @@ export interface MailingAddress {
 }
 
 export interface ShippingAddress extends MailingAddress {
+  /**
+   * Specifies whether the address should be saved to the buyer's account.
+   */
   oneTimeUse?: boolean;
 }

packages/ui-extensions/src/surfaces/checkout/api/standard/standard.ts

@@ -61,7 +61,7 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * The API version that was set in the extension config file.
    *
-   * @example '2023-07', '2023-10', '2024-01', '2024-04', 'unstable'
+   * @example '2023-07', '2023-10', '2024-01', '2024-04', '2024-07', 'unstable'
    */
   apiVersion: ApiVersion;
 
@@ -490,6 +490,16 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    */
   appliedGiftCards: StatefulRemoteSubscribable<AppliedGiftCard[]>;
 
+  /**
+   * The cart instructions used to create the checkout and possibly limit extension capabilities.
+   *
+   * These instructions should be checked prior to performing any actions that may be affected by them.
+   *
+   * For example, if you intend to add a discount code via the `applyDiscountCodeChange` method,
+   * check `discounts.canUpdateDiscountCodes` to ensure it's supported in this checkout.
+   */
+  instructions: StatefulRemoteSubscribable<CartInstructions>;
+
   /**
    * The metafields requested in the
    * [`shopify.extension.toml`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)
@@ -1906,3 +1916,94 @@ export interface TrackingConsentChangeResultError {
    */
   message: string;
 }
+
+export interface CartInstructions {
+  /**
+   * Cart instructions related to cart attributes.
+   */
+  attributes: AttributesCartInstructions;
+
+  /**
+   * Cart instructions related to delivery.
+   */
+  delivery: DeliveryCartInstructions;
+
+  /**
+   * Cart instructions related to discounts.
+   */
+  discounts: DiscountsCartInstructions;
+
+  /**
+   * Cart instructions related to cart lines.
+   */
+  lines: CartLinesCartInstructions;
+
+  /**
+   * Cart instructions related to metafields.
+   */
+  metafields: MetafieldsCartInstructions;
+
+  /**
+   * Cart instructions related to notes.
+   */
+  notes: NotesCartInstructions;
+}
+
+export interface AttributesCartInstructions {
+  /**
+   * Indicates whether or not cart attributes can be updated.
+   */
+  canUpdateAttributes: boolean;
+}
+
+export interface DeliveryCartInstructions {
+  /**
+   * Indicates whether a buyer can select a custom address.
+   *
+   * When true, this implies extensions can update the delivery address.
+   */
+  canSelectCustomAddress: boolean;
+}
+
+export interface DiscountsCartInstructions {
+  /**
+   * Indicates whether or not discount codes can be updated.
+   */
+  canUpdateDiscountCodes: boolean;
+}
+
+export interface CartLinesCartInstructions {
+  /**
+   * Indicates whether or not new cart lines can be added.
+   */
+  canAddCartLine: boolean;
+
+  /**
+   * Indicates whether or not cart lines can be removed.
+   */
+  canRemoveCartLine: boolean;
+
+  /**
+   * Indicates whether or not cart lines can be updated.
+   */
+  canUpdateCartLine: boolean;
+}
+
+export interface MetafieldsCartInstructions {
+  /**
+   * Indicates whether or not cart metafields can be added or updated.
+   */
+  canSetCartMetafields: boolean;
+
+  /**
+   * Indicates whether or not cart metafields can be deleted.
+   */
+  canDeleteCartMetafield: boolean;
+}
+
+export interface NotesCartInstructions {
+  /**
+   * Indicates whether or not notes can be updated.
+   */
+  canUpdateNote: boolean;
+}

packages/ui-extensions/src/surfaces/checkout/targets.ts

@@ -863,6 +863,7 @@ export interface CustomerAccountStandardApi<
     | 'extension'
     | 'extensionPoint'
     | 'i18n'
+    | 'instructions'
     | 'lines'
     | 'localization'
     | 'metafields'