@shopify/ui-extensions 2026.1.2 → 2026.1.4

package/src/surfaces/checkout/api/checkout/checkout.ts

@@ -6,280 +6,337 @@ import type {
 } from '../shared';
 
 /**
- * Removes a note
+ * Clears the buyer's note from the checkout. Pass this to `applyNoteChange()` to remove any existing note.
  */
 export interface NoteRemoveChange {
   /**
-   * The type of the `NoteRemoveChange` API.
+   * Identifies this as a note removal. Set this when creating a change to clear the buyer's note.
    */
   type: 'removeNote';
 }
 
 /**
- * An Update to a note on the order.
- * for example, the buyer could request detailed packaging instructions in an order note
+ * Sets or replaces the buyer's note on the checkout. Pass this to `applyNoteChange()` to update the note.
  */
 export interface NoteUpdateChange {
   /**
-   * The type of the `NoteUpdateChange` API.
+   * Identifies this as a note update. Set this when creating a change to set or replace the buyer's note.
    */
   type: 'updateNote';
   /**
-   * The new value of the note.
+   * The text to set as the buyer's note. This replaces any existing note entirely rather than appending to it.
    */
   note: string;
 }
 
+/**
+ * The input for `applyNoteChange()`. Pass either a `NoteUpdateChange` (with `type: 'updateNote'`) to set the note or a `NoteRemoveChange` (with `type: 'removeNote'`) to clear it.
+ */
 export type NoteChange = NoteRemoveChange | NoteUpdateChange;
 
+/**
+ * The result of a successful note change. The `type` property is `'success'`.
+ */
 export interface NoteChangeResultSuccess {
   /**
-   * The type of the `NoteChangeResultSuccess` API.
+   * Indicates that the note change was applied successfully.
    */
   type: 'success';
 }
 
+/**
+ * The result of a failed note change. Check the `message` property for details about what went wrong.
+ */
 export interface NoteChangeResultError {
   /**
-   * The type of the `NoteChangeResultError` API.
+   * Indicates that the note change couldn't be applied. Check the `message` property for details.
    */
   type: 'error';
 
   /**
    * A message that explains the error. This message is useful for debugging.
-   * It is **not** localized, and therefore should not be presented directly
+   * It isn't localized and shouldn't be displayed to the buyer.
+   *
+   * Render your own localized error text rather than displaying this message
    * to the buyer.
    */
   message: string;
 }
 
+/**
+ * The result of calling `applyNoteChange()`. Use the `type` property to determine whether the change succeeded or failed.
+ */
 export type NoteChangeResult = NoteChangeResultSuccess | NoteChangeResultError;
 
 /**
- * Updates an attribute on the order. If an attribute with the
- * provided key does not already exist, it gets created.
+ * Updates an attribute on the cart and checkout. If an attribute with the
+ * provided key doesn't already exist, then it gets created.
  */
 export interface AttributeUpdateChange {
   /**
-   * The type of the `AttributeUpdateChange` API.
+   * Identifies this as an attribute update or creation. Set this when creating a change to add or replace an attribute value.
    */
   type: 'updateAttribute';
 
   /**
-   * Key of the attribute to add or update
+   * The key of the attribute to add or update. If an attribute with this key
+   * already exists, then its value is replaced.
    */
   key: string;
 
   /**
-   * Value for the attribute to add or update
+   * The new value for the attribute.
    */
   value: string;
 }
 
 /**
- * Removes an attribute on the order if an attribute with the
- * provided key already exists.
+ * Removes an attribute from the checkout. Pass this to `applyAttributeChange()` to delete an attribute by key. If the key doesn't exist, then the change has no effect.
  */
 export interface AttributeRemoveChange {
   /**
-   * The type of the `AttributeRemoveChange` API.
+   * Identifies this as an attribute removal. Set this when creating a change to delete an attribute by key.
    */
   type: 'removeAttribute';
 
   /**
-   * Key of the attribute to remove
+   * The key of the attribute to remove.
    */
   key: string;
 }
 
+/**
+ * The input for `applyAttributeChange()`. Pass either an `AttributeUpdateChange` (with `type: 'updateAttribute'`) to set the attribute or an `AttributeRemoveChange` (with `type: 'removeAttribute'`) to delete it.
+ */
 export type AttributeChange = AttributeUpdateChange | AttributeRemoveChange;
 
 /**
- * The returned result of a successful update to an attribute.
+ * The result of a successful attribute change. The `type` property is `'success'`.
  */
 export interface AttributeChangeResultSuccess {
   /**
-   * The type of the `AttributeChangeResultSuccess` API.
+   * Indicates that the attribute change was applied successfully.
    */
   type: 'success';
 }
 
 /**
- * The returned result of an unsuccessful update to an attribute
- * with a message detailing the type of error that occurred.
+ * The result of a failed attribute change. Check the `message` property for details about what went wrong.
  */
 export interface AttributeChangeResultError {
   /**
-   * The type of the `AttributeChangeResultError` API.
+   * Indicates that the attribute change couldn't be applied. Check the `message` property for details.
    */
   type: 'error';
 
   /**
    * A message that explains the error. This message is useful for debugging.
-   * It is **not** localized, and therefore should not be presented directly
-   * to the buyer.
+   * It isn't localized and shouldn't be displayed to the buyer.
    */
   message: string;
 }
 
+/**
+ * The result of calling `applyAttributeChange()`. Use the `type` property to determine whether the change succeeded or failed.
+ */
 export type AttributeChangeResult =
   | AttributeChangeResultSuccess
   | AttributeChangeResultError;
 
+/**
+ * The result of a successful cart line change. The `type` property is `'success'`.
+ */
 export interface CartLineChangeResultSuccess {
   /**
-   * Indicates that the line item was changed successfully.
+   * Indicates that the cart line change was applied successfully.
    */
   type: 'success';
 }
 
+/**
+ * The result of a failed cart line change. Check the `message` property for details about what went wrong.
+ */
 export interface CartLineChangeResultError {
   /**
-   * Indicates that the line item was not changed successfully. Refer to the `message` property for details about the error.
+   * Indicates that the line item wasn't changed successfully. Refer to the `message` property for details about the error.
    */
   type: 'error';
 
   /**
    * A message that explains the error. This message is useful for debugging.
-   * It is **not** localized, and therefore should not be presented directly
+   * It isn't localized and shouldn't be displayed to the buyer.
+   *
+   * Render your own localized error text rather than displaying this message
    * to the buyer.
    */
   message: string;
 }
 
+/**
+ * The result of calling `applyCartLinesChange()`. Use the `type` property to determine whether the change succeeded or failed.
+ */
 export type CartLineChangeResult =
   | CartLineChangeResultSuccess
   | CartLineChangeResultError;
 
+/**
+ * The input for `applyCartLinesChange()`. Use the `type` property to specify the operation.
+ *
+ * - `CartLineAddChange` (`type: 'addCartLine'`): Adds a new line item to the cart.
+ * - `CartLineRemoveChange` (`type: 'removeCartLine'`): Removes an existing line item.
+ * - `CartLineUpdateChange` (`type: 'updateCartLine'`): Updates an existing line item's quantity, variant, or attributes.
+ */
 export type CartLineChange =
   | CartLineAddChange
   | CartLineRemoveChange
   | CartLineUpdateChange;
 
+/**
+ * Adds a new line item to the cart. Pass this to `applyCartLinesChange()` to add a product variant with a specified quantity and optional attributes.
+ */
 export interface CartLineAddChange {
   /**
-   * An identifier for changes that add line items.
+   * Identifies this as a line item addition. Set this when creating a change to add a new product to the cart.
    */
   type: 'addCartLine';
 
   /**
-   * The merchandise ID being added.
+   * The globally-unique identifier of the product variant to add.
    * @example 'gid://shopify/ProductVariant/123'
    */
   merchandiseId: string;
 
   /**
-   * The quantity of the merchandise being added.
+   * The number of items to add. Must be a positive integer.
    */
   quantity: number;
 
   /**
-   * The attributes associated with the line item.
+   * Custom key-value attributes to attach to the new line item.
    */
   attributes?: Attribute[];
 
   /**
-   * The identifier of the selling plan that the merchandise is being purchased
-   * with.
+   * The identifier of the [selling plan](https://shopify.dev/docs/apps/build/purchase-options/subscriptions) to associate with this line item, such as a subscription or pre-order plan.
    */
   sellingPlanId?: SellingPlan['id'];
 
   /**
-   * The identifier for the associated parent cart line.
+   * The parent cart line to associate the new item with, identified by either `lineId` or `merchandiseId`. Use this when adding child items to a bundle.
    */
   parent?: {lineId: string} | {merchandiseId: string};
 }
 
+/**
+ * Removes an existing line item from the cart. Pass this to `applyCartLinesChange()` to remove a specified quantity of a line item.
+ */
 export interface CartLineRemoveChange {
   /**
-   * An identifier for changes that remove line items.
+   * Identifies this as a line item removal. Set this when creating a change to remove a product from the cart.
    */
   type: 'removeCartLine';
 
   /**
-   * Line Item ID.
+   * The unique identifier of the cart line to remove. Look up the current ID from `lines` before calling, because cart line IDs aren't stable.
    * @example 'gid://shopify/CartLine/123'
    */
   id: string;
 
   /**
-   * The quantity being removed for this line item.
+   * The number of items to remove from this line.
    */
   quantity: number;
 }
 
+/**
+ * Updates an existing line item in the cart. Pass this to `applyCartLinesChange()` to change a line item's quantity, variant, selling plan, or attributes.
+ */
 export interface CartLineUpdateChange {
   /**
-   * An identifier for changes that update line items.
+   * Identifies this as a line item update. Set this when creating a change to modify a line item's quantity, variant, or attributes.
    */
   type: 'updateCartLine';
 
   /**
-   * Line Item ID.
+   * The unique identifier of the cart line to update. Look up the current ID from `lines` before calling, because cart line IDs aren't stable.
    * @example 'gid://shopify/CartLine/123'
    */
   id: string;
 
   /**
-   * The new merchandise ID for the line item.
+   * The new product variant to swap in for this line item. Only provide this if you want to change the variant.
    * @example 'gid://shopify/ProductVariant/123'
    */
 
   merchandiseId?: string;
   /**
-   * The new quantity for the line item.
+   * The new quantity for this line item. Only provide this if you want to change the quantity.
    */
   quantity?: number;
 
   /**
-   * The new attributes for the line item.
+   * The new custom key-value attributes for this line item. Replaces all existing attributes when provided.
    */
   attributes?: Attribute[];
 
   /**
-   * The identifier of the selling plan that the merchandise is being purchased
-   * with or `null` to remove the the product from the selling plan.
+   * The [selling plan](https://shopify.dev/docs/apps/build/purchase-options/subscriptions) to associate with this line item. Pass `null` to remove the item from its current selling plan.
    */
   sellingPlanId?: SellingPlan['id'] | null;
 
   /**
-   * The identifier for the associated parent cart line.
+   * The parent cart line to associate this item with. Use this when updating the parent relationship for bundled items.
    */
   parent?: {lineId: string} | {merchandiseId: string};
 }
 
+/**
+ * The input for `applyDiscountCodeChange()`. Pass either a `DiscountCodeAddChange` (with `type: 'addDiscountCode'`) to apply a code or a `DiscountCodeRemoveChange` (with `type: 'removeDiscountCode'`) to remove it.
+ */
 export type DiscountCodeChange =
   | DiscountCodeAddChange
   | DiscountCodeRemoveChange;
 
+/**
+ * The result of calling `applyDiscountCodeChange()`. Use the `type` property to determine whether the change succeeded or failed.
+ */
 export type DiscountCodeChangeResult =
   | DiscountCodeChangeResultSuccess
   | DiscountCodeChangeResultError;
 
+/**
+ * Applies a discount code to the checkout. Pass this to `applyDiscountCodeChange()` to add a code.
+ */
 export interface DiscountCodeAddChange {
   /**
-   * The type of the `DiscountCodeChange` API.
+   * Identifies this as a discount code addition. Set this when creating a change to apply a discount code to the checkout.
    */
   type: 'addDiscountCode';
 
   /**
-   * The code for the discount (case-insensitive)
+   * The discount code to apply. Codes are case-insensitive.
    */
   code: string;
 }
 
+/**
+ * Removes a discount code from the checkout. Pass this to `applyDiscountCodeChange()` to remove a code.
+ */
 export interface DiscountCodeRemoveChange {
   /**
-   * The type of the `DiscountCodeChange` API.
+   * Identifies this as a discount code removal. Set this when creating a change to remove a discount code from the checkout.
    */
   type: 'removeDiscountCode';
 
   /**
-   * The code for the discount (case-insensitive)
+   * The discount code to remove. Codes are case-insensitive.
    */
   code: string;
 }
 
+/**
+ * The result of a successful discount code change. The `type` property is `'success'`.
+ */
 export interface DiscountCodeChangeResultSuccess {
   /**
    * Indicates that the discount code change was applied successfully.
@@ -287,50 +344,68 @@ export interface DiscountCodeChangeResultSuccess {
   type: 'success';
 }
 
+/**
+ * The result of a failed discount code change. Check the `message` property for details about what went wrong.
+ */
 export interface DiscountCodeChangeResultError {
   /**
-   * Indicates that the discount code change failed.
+   * Indicates that the discount code change couldn't be applied. Check the `message` property for details.
    */
   type: 'error';
 
   /**
    * A message that explains the error. This message is useful for debugging.
-   * It is **not** localized, and therefore should not be presented directly
-   * to the buyer.
+   * It isn't localized and shouldn't be displayed to the buyer.
    */
   message: string;
 }
 
+/**
+ * The input for `applyGiftCardChange()`. Pass either a `GiftCardAddChange` (with `type: 'addGiftCard'`) to apply a gift card or a `GiftCardRemoveChange` (with `type: 'removeGiftCard'`) to remove it.
+ */
 export type GiftCardChange = GiftCardAddChange | GiftCardRemoveChange;
 
+/**
+ * The result of calling `applyGiftCardChange()`. Use the `type` property to determine whether the change succeeded or failed.
+ */
 export type GiftCardChangeResult =
   | GiftCardChangeResultSuccess
   | GiftCardChangeResultError;
 
+/**
+ * Applies a gift card to the checkout. Pass this to `applyGiftCardChange()` to add a gift card.
+ */
 export interface GiftCardAddChange {
   /**
-   * The type of the `GiftCardChange` API.
+   * Identifies this as a gift card addition. Set this when creating a change to apply a gift card to the checkout.
    */
   type: 'addGiftCard';
 
   /**
-   * Gift card code.
+   * The full gift card code to apply to the checkout.
    */
   code: string;
 }
 
+/**
+ * Removes a gift card from the checkout. Pass this to `applyGiftCardChange()` to remove a gift card.
+ */
 export interface GiftCardRemoveChange {
   /**
-   * The type of the `GiftCardChange` API.
+   * Identifies this as a gift card removal. Set this when creating a change to remove a gift card from the checkout.
    */
   type: 'removeGiftCard';
 
   /**
-   * The full gift card code, or the last four digits of the code.
+   * The gift card code to remove. You can pass either the full code or
+   * just the last four characters.
    */
   code: string;
 }
 
+/**
+ * The result of a successful gift card change. The `type` property is `'success'`.
+ */
 export interface GiftCardChangeResultSuccess {
   /**
    * Indicates that the gift card change was applied successfully.
@@ -338,15 +413,20 @@ export interface GiftCardChangeResultSuccess {
   type: 'success';
 }
 
+/**
+ * The result of a failed gift card change. Check the `message` property for details about what went wrong.
+ */
 export interface GiftCardChangeResultError {
   /**
-   * Indicates that the gift card change failed.
+   * Indicates that the gift card change couldn't be applied. Check the `message` property for details.
    */
   type: 'error';
 
   /**
    * A message that explains the error. This message is useful for debugging.
-   * It is **not** localized, and therefore should not be presented directly
+   * It isn't localized and shouldn't be displayed to the buyer.
+   *
+   * Render your own localized error text rather than displaying this message
    * to the buyer.
    */
   message: string;
@@ -374,10 +454,10 @@ export interface MetafieldRemoveChange {
   namespace: string;
 }
 
-/** Removes a cart metafield. */
+/** Removes a cart [metafield](https://shopify.dev/docs/apps/build/custom-data/metafields). Pass this to `applyMetafieldChange()` to delete a metafield by key and namespace. */
 export interface MetafieldRemoveCartChange {
   /**
-   * The type of the `MetafieldRemoveChange` API.
+   * Identifies this as a cart metafield removal. Set this when creating a change to delete an existing metafield by key and namespace.
    */
   type: 'removeCartMetafield';
 
@@ -415,203 +495,234 @@ export interface MetafieldUpdateChange {
   value: string | number;
 
   /**
-   * The metafield’s information type.
+   * The metafield's information type.
    */
   valueType: 'integer' | 'string' | 'json_string';
 }
 
 /**
- * Updates a cart metafield. If a metafield with the
- * provided key and namespace does not already exist, it gets created.
+ * Creates or updates a cart [metafield](https://shopify.dev/docs/apps/build/custom-data/metafields). Pass this to `applyMetafieldChange()` to set a metafield value. If a metafield with the provided key and namespace doesn't already exist, then it gets created.
  */
 export interface MetafieldUpdateCartChange {
   /**
-   * The type of the `MetafieldUpdateChange` API.
+   * Identifies this as a cart metafield creation or update. Set this when creating a change to set a metafield value.
    */
   type: 'updateCartMetafield';
 
+  /**
+   * The metafield data to set on the cart. If a metafield with this key and namespace already exists, then its value is replaced.
+   */
   metafield: {
     /** The name of the metafield to update. */
     key: string;
 
-    /** The namespace of the metafield to add. */
+    /** The namespace of the metafield to update. */
     namespace?: string;
 
     /** The new information to store in the metafield. */
     value: string;
 
     /**
-     * The metafield’s information type.
-     * See the [`metafields documentation`](https://shopify.dev/docs/apps/custom-data/metafields/types) for a list of supported types.
+     * The metafield's information type.
+     * See the [metafield types documentation](https://shopify.dev/docs/apps/build/custom-data/metafields/list-of-data-types) for a list of supported types.
      */
     type: string;
   };
 }
 
+/**
+ * The input for `applyMetafieldChange()`. Use the `type` property to specify the operation.
+ *
+ * - `MetafieldRemoveCartChange` (`type: 'removeCartMetafield'`): Removes an existing cart [metafield](https://shopify.dev/docs/apps/build/custom-data/metafields).
+ * - `MetafieldUpdateCartChange` (`type: 'updateCartMetafield'`): Creates or updates a cart metafield.
+ * - `MetafieldRemoveChange` (`type: 'removeMetafield'`) - Deprecated. Use `MetafieldRemoveCartChange` instead.
+ * - `MetafieldUpdateChange` (`type: 'updateMetafield'`) - Deprecated. Use `MetafieldUpdateCartChange` instead.
+ */
 export type MetafieldChange =
   | MetafieldRemoveChange
   | MetafieldUpdateChange
   | MetafieldRemoveCartChange
   | MetafieldUpdateCartChange;
 
+/**
+ * The result of a successful metafield change. The `type` property is `'success'`.
+ */
 export interface MetafieldChangeResultSuccess {
   /**
-   * The type of the `MetafieldChangeResultSuccess` API.
+   * Indicates that the metafield change was applied successfully.
    */
   type: 'success';
 }
 
+/**
+ * The result of a failed metafield change. Check the `message` property for details about what went wrong.
+ */
 export interface MetafieldChangeResultError {
   /**
-   * The type of the `MetafieldChangeResultError` API.
+   * Indicates that the metafield change couldn't be applied. Check the `message` property for details.
    */
   type: 'error';
 
   /**
    * A message that explains the error. This message is useful for debugging.
-   * It is **not** localized, and therefore should not be presented directly
+   * It isn't localized and shouldn't be displayed to the buyer.
+   *
+   * Render your own localized error text rather than displaying this message
    * to the buyer.
    */
   message: string;
 }
 
+/**
+ * The result of calling `applyMetafieldChange()`. Use the `type` property to determine whether the change succeeded or failed.
+ */
 export type MetafieldChangeResult =
   | MetafieldChangeResultSuccess
   | MetafieldChangeResultError;
 
+/**
+ * Updates the buyer's shipping address on the checkout. Pass this to `applyShippingAddressChange()` to modify specific address fields without replacing the entire address.
+ */
 export interface ShippingAddressUpdateChange {
   /**
-   * The type of the `ShippingAddressUpdateChange` API.
+   * Identifies this as a shipping address update. This is the only supported change type for `applyShippingAddressChange()`.
    */
   type: 'updateShippingAddress';
 
   /**
    * Fields to update in the shipping address. You only need to provide
-   * values for the fields you want to update — any fields you do not list
-   * will keep their current values.
+   * values for the fields you want to update. Any fields you don't list
+   * keep their current values.
    */
   address: Partial<ShippingAddress>;
 }
 
+/**
+ * The input for `applyShippingAddressChange()`. Currently only supports `ShippingAddressUpdateChange` (with `type: 'updateShippingAddress'`).
+ */
 export type ShippingAddressChange = ShippingAddressUpdateChange;
 
 /**
- * The returned result of a successful update to the shipping address.
+ * The result of a successful shipping address change. The `type` property is `'success'` and `errors` is `null`.
  */
 export interface ShippingAddressChangeResultSuccess {
   /**
-   * The type of the `ShippingAddressChangeResultSuccess` API.
+   * Indicates that the shipping address change was applied successfully.
    */
   type: 'success';
 
+  /**
+   * Always `null` for a successful address change. Present so that you can
+   * check `result.errors` without narrowing the union type first.
+   */
   errors: null;
 }
 
 /**
- * An error corresponding to a particular field from a given change
+ * An error corresponding to a particular field from a given change. Use the `field` property to determine which address field caused the error.
  */
 export interface ShippingAddressChangeFieldError {
   /**
-   * field key from MailingAddress where the error occurred
+   * The `MailingAddress` field that caused the error, such as `'countryCode'` or `'zip'`. The value is `undefined` if the error isn't specific to a single field.
    */
   field?: keyof MailingAddress;
 
   /**
    * A message that explains the error. This message is useful for debugging.
-   * It is **not** localized, and therefore should not be presented directly
-   * to the buyer.
+   * It isn't localized and shouldn't be displayed to the buyer.
    */
   message: string;
 }
 
 /**
- * The returned result of an update to the shipping address
- * with a messages detailing the type of errors that occurred.
+ * The result of a failed shipping address change. Check the `errors` array for field-level details about what went wrong.
  */
 export interface ShippingAddressChangeResultError {
   /**
-   * The type of the `ShippingAddressChangeResultError` API.
+   * Indicates that the shipping address change couldn't be applied. Check the `errors` array for field-level details.
    */
   type: 'error';
 
   /**
-   * The errors corresponding to particular fields from a given change
+   * The list of field-level errors that prevented the address change. Each entry identifies which address field failed and why.
    */
   errors: ShippingAddressChangeFieldError[];
 }
 
+/**
+ * The result of calling `applyShippingAddressChange()`. Use the `type` property to determine whether the change succeeded or failed. On failure, the `errors` array contains field-level details.
+ */
 export type ShippingAddressChangeResult =
   | ShippingAddressChangeResultSuccess
   | ShippingAddressChangeResultError;
 
+/**
+ * Methods for modifying the checkout, including cart lines, discount codes, gift cards, metafields, notes, attributes, and the shipping address. Each method returns a promise that resolves with a result indicating success or failure.
+ */
 export interface CheckoutApi {
   /**
-   * Performs an update on an attribute attached to the cart and checkout. If
-   * successful, this mutation results in an update to the value retrieved
-   * through the [`attributes`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/attributes#standardapi-propertydetail-attributes) property.
+   * Updates or removes an attribute on the cart and checkout. On success, the
+   * [`attributes`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/attributes#properties-propertydetail-attributes) property updates to reflect the change.
    *
-   * > Note: This method will return an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cart-instructions#standardapi-propertydetail-instructions) `attributes.canUpdateAttributes` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
+   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#properties-propertydetail-instructions) `attributes.canUpdateAttributes` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
    *
-   * @deprecated - Consumers should use cart metafields instead.
+   * @deprecated Use cart metafields instead.
    */
   applyAttributeChange(change: AttributeChange): Promise<AttributeChangeResult>;
 
   /**
-   * Performs an update on the merchandise line items. It resolves when the new
-   * line items have been negotiated and results in an update to the value
-   * retrieved through the
-   * [`lines`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cart-lines#standardapi-propertydetail-lines)
-   * property.
+   * Adds, removes, or updates line items in the cart. The returned promise resolves when the change has been applied by the server, and the [`lines`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-lines#properties-propertydetail-lines) property updates with the new state.
    *
-   * > Note: This method will return an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cart-instructions#standardapi-propertydetail-instructions) `lines.canAddCartLine` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
+   * Accepts a single change per call. To make multiple changes, call this
+   * method separately for each one.
+   *
+   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#properties-propertydetail-instructions) `lines.canAddCartLine` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
    */
   applyCartLinesChange(change: CartLineChange): Promise<CartLineChangeResult>;
 
   /**
-   * Performs an update on the discount codes.
-   * It resolves when the new discount codes have been negotiated and results in an update
-   * to the value retrieved through the [`discountCodes`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/discounts#standardapi-propertydetail-discountcodes) property.
+   * Adds or removes a discount code on the checkout. The returned promise resolves when the change has been applied by the server, and the [`discountCodes`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/discounts#properties-propertydetail-discountcodes) property updates with the new state.
    *
    * > Caution:
-   * > See [security considerations](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access) if your extension retrieves discount codes through a network call.
+   * > See [security considerations](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/configuration#network-access) if your extension retrieves discount codes through a network call.
    *
-   * > Note: This method will return an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cart-instructions#standardapi-propertydetail-instructions) `discounts.canUpdateDiscountCodes` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
+   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#properties-propertydetail-instructions) `discounts.canUpdateDiscountCodes` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
    */
   applyDiscountCodeChange(
     change: DiscountCodeChange,
   ): Promise<DiscountCodeChangeResult>;
 
   /**
-   * Performs an update on the gift cards.
-   * It resolves when gift card change have been negotiated and results in an update
-   * to the value retrieved through the [`appliedGiftCards`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/gift-cards#standardapi-propertydetail-appliedgiftcards) property.
+   * Adds or removes a gift card from the checkout. The returned promise resolves when the change has been applied by the server, and the [`appliedGiftCards`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/gift-cards#properties-propertydetail-appliedgiftcards) property updates with the new state.
+   *
+   * Unlike other write operations, gift card changes aren't gated by a cart
+   * instruction flag.
    *
    * > Caution:
-   * > See [security considerations](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access) if your extension retrieves gift card codes through a network call.
+   * > See [security considerations](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/configuration#network-access) if your extension retrieves gift card codes through a network call.
    *
-   * > Note: This method will return an error if the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
+   * > Note: This method returns an error if the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
    */
   applyGiftCardChange(change: GiftCardChange): Promise<GiftCardChangeResult>;
 
   /**
-   * Performs an update on a piece of metadata attached to the checkout. If
-   * successful, this mutation results in an update to the value retrieved
-   * through the [`metafields`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/metafields#standardapi-propertydetail-metafields) property.
+   * Creates, updates, or removes a cart metafield on the checkout. On success, the
+   * [`metafields`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/metafields#properties-propertydetail-metafields) property updates to reflect the change.
    *
-   * Cart metafields will be copied to order metafields at order creation time if there is a matching order metafield definition with the [`cart to order copyable`](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#cart-to-order-copyable) capability enabled.
+   * Cart metafields are copied to order metafields at order creation time if there's a matching order metafield definition with the [`cart to order copyable`](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#cart-to-order-copyable) capability enabled.
    *
-   * > Caution: `MetafieldRemoveChange` and `MetafieldUpdateChange` are deprecated. Use cart metafields with `MetafieldRemoveCartChange` and `MetafieldUpdateCartChange` instead. If `MetafieldUpdateChange` writes a metafield with the same namespace and key as a cart metafield that’s configured to copy, the cart metafield won’t be copied.
+   * > Caution: `MetafieldRemoveChange` and `MetafieldUpdateChange` are deprecated. Use cart metafields with `MetafieldRemoveCartChange` and `MetafieldUpdateCartChange` instead. If `MetafieldUpdateChange` writes a metafield with the same namespace and key as a cart metafield that's configured to copy, the cart metafield won't be copied.
    *
-   * > Note: This method will return an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cart-instructions#standardapi-propertydetail-instructions) `metafields.canSetCartMetafields` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
+   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#properties-propertydetail-instructions) `metafields.canSetCartMetafields` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
    */
   applyMetafieldChange(change: MetafieldChange): Promise<MetafieldChangeResult>;
 
   /**
-   * Performs an update on the note attached to the cart and checkout. If
-   * successful, this mutation results in an update to the value retrieved
-   * through the [`note`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/note#standardapi-propertydetail-note) property.
+   * Sets or removes the buyer's note on the checkout. On success, the
+   * [`note`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/note#properties-propertydetail-note)
+   * property updates to reflect the change.
    *
-   * > Note: This method will return an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cart-instructions#standardapi-propertydetail-instructions) `notes.canUpdateNote` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
+   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#properties-propertydetail-instructions) `notes.canUpdateNote` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
    */
   applyNoteChange(change: NoteChange): Promise<NoteChangeResult>;
 
@@ -621,14 +732,13 @@ export interface CheckoutApi {
   experimentalIsShopAppStyle?: boolean;
 
   /**
-   * Performs an update of the shipping address. Shipping address changes will
-   * completely overwrite the existing shipping address added by the user without
-   * any prompts. If successful, this mutation results in an update to the value
-   * retrieved through the `shippingAddress` property.
+   * Updates the buyer's shipping address on the checkout. The provided fields
+   * are merged into the existing address without prompting the buyer. On success,
+   * the `shippingAddress` property updates to reflect the change.
    *
-   * > Note: This method will return an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cart-instructions#standardapi-propertydetail-instructions) `delivery.canSelectCustomAddress` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
+   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#properties-propertydetail-instructions) `delivery.canSelectCustomAddress` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
    */
   applyShippingAddressChange?(
     change: ShippingAddressChange,