# CheckoutApi


This API object is provided to extensions registered for the extension targets that appear exclusively pre-purchase.

It extends the [StandardApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi) and provides the write apis for the checkout data.


```jsx
import {
  reactExtension,
  Checkbox,
  useApplyAttributeChange,
} from '@shopify/ui-extensions-react/checkout';

// 1. Choose an extension target
export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const applyAttributeChange =
    useApplyAttributeChange();

  // 2. Render a UI
  return (
    <Checkbox onChange={onCheckboxChange}>
      I would like to receive a free gift with my
      order
    </Checkbox>
  );

  // 3. Call API methods to modify the checkout
  async function onCheckboxChange(isChecked) {
    const result = await applyAttributeChange({
      key: 'requestedFreeGift',
      type: 'updateAttribute',
      value: isChecked ? 'yes' : 'no',
    });
    console.log(
      'applyAttributeChange result',
      result,
    );
  }
}

```

```js
import {
  extension,
  Checkbox,
} from '@shopify/ui-extensions/checkout';

// 1. Choose an extension target
export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    // 2. Render a UI
    root.appendChild(
      root.createComponent(
        Checkbox,
        {
          onChange: onCheckboxChange,
        },
        'I would like to receive a free gift with my order',
      ),
    );

    // 3. Call API methods to modify the checkout
    async function onCheckboxChange(isChecked) {
      const result =
        await api.applyAttributeChange({
          key: 'requestedFreeGift',
          type: 'updateAttribute',
          value: isChecked ? 'yes' : 'no',
        });
      console.log(
        'applyAttributeChange result',
        result,
      );
    }
  },
);

```

## Properties

See the [StandardApi examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi#examples) for more information on how to use the API.

### CheckoutApi

### applyAttributeChange

value: `(change: AttributeUpdateChange) => Promise<AttributeChangeResult>`

  - AttributeUpdateChange: export interface AttributeUpdateChange {
  /**
   * The type of the `AttributeUpdateChange` API.
   */
  type: 'updateAttribute';

  /**
   * Key of the attribute to add or update
   */
  key: string;

  /**
   * Value for the attribute to add or update
   */
  value: string;
}
  - Attribute: export interface Attribute {
  /**
   * The key for the attribute.
   */
  key: string;

  /**
   * The value for the attribute.
   */
  value: string;
}
  - AttributeChangeResult: AttributeChangeResultSuccess | AttributeChangeResultError
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/standardapi#properties-propertydetail-applyattributechange) property.

> Note: This method will return an error if the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.

### applyCartLinesChange

value: `(change: CartLineChange) => Promise<CartLineChangeResult>`

  - CartLineChange: CartLineAddChange | CartLineRemoveChange | CartLineUpdateChange
  - CartLine: export interface CartLine {
  /**
   * These line item IDs are not stable at the moment, they might change after
   * any operations on the line items. You should always look up for an updated
   * ID before any call to `applyCartLinesChange` because you'll need the ID to
   * create a `CartLineChange` object.
   * @example 'gid://shopify/CartLine/123'
   */
  id: string;

  /**
   * The merchandise being purchased.
   */
  merchandise: Merchandise;

  /**
   * The quantity of the merchandise being purchased.
   */
  quantity: number;

  /**
   * The details about the cost components attributed to the cart line.
   */
  cost: CartLineCost;

  /**
   * The line item additional custom attributes.
   */
  attributes: Attribute[];

  /**
   * Discounts applied to the cart line.
   */
  discountAllocations: CartDiscountAllocation[];

  /**
   * Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.
   */
  lineComponents: CartLineComponentType[];
}
  - CartLineChangeResult: CartLineChangeResultSuccess | CartLineChangeResultError
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/standardapi#properties-propertydetail-lines)
property.

> Note: This method will return an error if the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.

### applyDiscountCodeChange

value: `(change: DiscountCodeChange) => Promise<DiscountCodeChangeResult>`

  - DiscountCodeChange: DiscountCodeAddChange | DiscountCodeRemoveChange
  - DiscountCodeChangeResult: DiscountCodeChangeResultSuccess | DiscountCodeChangeResultError
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/standardapi#properties-propertydetail-discountcodes) property.

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

> Note: This method will return an error if the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.

### applyGiftCardChange

value: `(change: GiftCardChange) => Promise<GiftCardChangeResult>`

  - GiftCardChange: GiftCardAddChange | GiftCardRemoveChange
  - GiftCardChangeResult: GiftCardChangeResultSuccess | GiftCardChangeResultError
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/standardapi#properties-propertydetail-appliedgiftcards) property.

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

> Note: This method will return an error if the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.

### applyMetafieldChange

value: `(change: MetafieldChange) => Promise<MetafieldChangeResult>`

  - MetafieldChange: MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange
  - Metafield: export interface Metafield {
  /**
   * The name of the metafield. It must be between 3 and 30 characters in
   * length (inclusive).
   */
  key: string;

  /**
   * A container for a set of metafields. You need to define a custom
   * namespace for your metafields to distinguish them from the metafields
   * used by other apps. This must be between 2 and 20 characters in length (inclusive).
   */
  namespace: string;

  /**
   * The information to be stored as metadata.
   */
  value: string | number;

  /** The metafield’s information type. */
  valueType: 'integer' | 'string' | 'json_string';
}
  - MetafieldChangeResult: MetafieldChangeResultSuccess | MetafieldChangeResultError
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/standardapi#properties-propertydetail-metafields) property.

### applyNoteChange

value: `(change: NoteChange) => Promise<NoteChangeResult>`

  - NoteChange: NoteRemoveChange | NoteUpdateChange
  - NoteChangeResult: NoteChangeResultSuccess | NoteChangeResultError
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/standardapi#properties-propertydetail-note) property.

> Note: This method will return an error if the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.

### experimentalIsShopAppStyle

value: `boolean`


### applyShippingAddressChange

value: `(change: ShippingAddressUpdateChange) => Promise<ShippingAddressChangeResult>`

  - ShippingAddressUpdateChange: export interface ShippingAddressUpdateChange {
  /**
   * The type of the `ShippingAddressUpdateChange` API.
   */
  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.
   */
  address: Partial<MailingAddress>;
}
  - ShippingAddressChangeResult: ShippingAddressChangeResultSuccess | ShippingAddressChangeResultError
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.

{% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).

### AttributeUpdateChange

Updates an attribute on the order. If an attribute with the
provided key does not already exist, it gets created.

### type

value: `"updateAttribute"`

  - Attribute: export interface Attribute {
  /**
   * The key for the attribute.
   */
  key: string;

  /**
   * The value for the attribute.
   */
  value: string;
}
The type of the `AttributeUpdateChange` API.

### key

value: `string`

Key of the attribute to add or update

### value

value: `string`

Value for the attribute to add or update

### Attribute

### key

value: `string`

The key for the attribute.

### value

value: `string`

The value for the attribute.

### AttributeChangeResultSuccess

The returned result of a successful update to an attribute.

### type

value: `"success"`

The type of the `AttributeChangeResultSuccess` API.

### AttributeChangeResultError

The returned result of an unsuccessful update to an attribute
with a message detailing the type of error that occurred.

### type

value: `"error"`

The type of the `AttributeChangeResultError` API.

### message

value: `string`

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.

### CartLineAddChange

### type

value: `"addCartLine"`

  - CartLine: export interface CartLine {
  /**
   * These line item IDs are not stable at the moment, they might change after
   * any operations on the line items. You should always look up for an updated
   * ID before any call to `applyCartLinesChange` because you'll need the ID to
   * create a `CartLineChange` object.
   * @example 'gid://shopify/CartLine/123'
   */
  id: string;

  /**
   * The merchandise being purchased.
   */
  merchandise: Merchandise;

  /**
   * The quantity of the merchandise being purchased.
   */
  quantity: number;

  /**
   * The details about the cost components attributed to the cart line.
   */
  cost: CartLineCost;

  /**
   * The line item additional custom attributes.
   */
  attributes: Attribute[];

  /**
   * Discounts applied to the cart line.
   */
  discountAllocations: CartDiscountAllocation[];

  /**
   * Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.
   */
  lineComponents: CartLineComponentType[];
}
An identifier for changes that add line items.

### merchandiseId

value: `string`

The merchandise ID being added.

### quantity

value: `number`

The quantity of the merchandise being added.

### attributes

value: `Attribute[]`

  - Attribute: export interface Attribute {
  /**
   * The key for the attribute.
   */
  key: string;

  /**
   * The value for the attribute.
   */
  value: string;
}
The attributes associated with the line item.

### sellingPlanId

value: `string`

The identifier of the selling plan that the merchandise is being purchased
with.

### CartLine

### id

value: `string`

These line item IDs are not stable at the moment, they might change after
any operations on the line items. You should always look up for an updated
ID before any call to `applyCartLinesChange` because you'll need the ID to
create a `CartLineChange` object.

### merchandise

value: `Merchandise`

  - Merchandise: ProductVariant
The merchandise being purchased.

### quantity

value: `number`

The quantity of the merchandise being purchased.

### cost

value: `CartLineCost`

  - CartLine: export interface CartLine {
  /**
   * These line item IDs are not stable at the moment, they might change after
   * any operations on the line items. You should always look up for an updated
   * ID before any call to `applyCartLinesChange` because you'll need the ID to
   * create a `CartLineChange` object.
   * @example 'gid://shopify/CartLine/123'
   */
  id: string;

  /**
   * The merchandise being purchased.
   */
  merchandise: Merchandise;

  /**
   * The quantity of the merchandise being purchased.
   */
  quantity: number;

  /**
   * The details about the cost components attributed to the cart line.
   */
  cost: CartLineCost;

  /**
   * The line item additional custom attributes.
   */
  attributes: Attribute[];

  /**
   * Discounts applied to the cart line.
   */
  discountAllocations: CartDiscountAllocation[];

  /**
   * Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.
   */
  lineComponents: CartLineComponentType[];
}
  - CartLineCost: export interface CartLineCost {
  /**
   * The total amount after reductions the buyer can expect to pay that is directly attributable to a single
   * cart line.
   */
  totalAmount: Money;
}
The details about the cost components attributed to the cart line.

### attributes

value: `Attribute[]`

  - Attribute: export interface Attribute {
  /**
   * The key for the attribute.
   */
  key: string;

  /**
   * The value for the attribute.
   */
  value: string;
}
The line item additional custom attributes.

### discountAllocations

value: `CartDiscountAllocation[]`

  - CartDiscountAllocation: CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation
Discounts applied to the cart line.

### lineComponents

value: `CartBundleLineComponent[]`

  - CartBundleLineComponent: export interface CartBundleLineComponent {
  type: 'bundle';

  /**
   * A unique identifier for the bundle line component.
   *
   * This ID is not stable. If an operation updates the line items in any way, all IDs could change.
   *
   * @example 'gid://shopify/CartLineComponent/123'
   */
  id: string;

  /**
   * The merchandise of this bundle line component.
   */
  merchandise: Merchandise;

  /**
   * The quantity of merchandise being purchased.
   */
  quantity: number;

  /**
   * The cost attributed to this bundle line component.
   */
  cost: CartLineCost;

  /**
   * Additional custom attributes for the bundle line component.
   *
   * @example [{key: 'engraving', value: 'hello world'}]
   */
  attributes: Attribute[];
}
Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.

### Merchandise

### type

value: `"variant"`


### id

value: `string`

A globally-unique identifier.

### title

value: `string`

The product variant’s title.

### subtitle

value: `string`

The product variant's subtitle.

### image

value: `ImageDetails`

  - ImageDetails: export interface ImageDetails {
  /**
   * The image URL.
   */
  url: string;

  /**
   * The alternative text for the image.
   */
  altText?: string;
}
Image associated with the product variant. This field falls back to the product
image if no image is available.

### selectedOptions

value: `SelectedOption[]`

  - SelectedOption: export interface SelectedOption {
  /**
   * The name of the merchandise option.
   */
  name: string;

  /**
   * The value of the merchandise option.
   */
  value: string;
}
List of product options applied to the variant.

### product

value: `Product`

  - Product: export interface Product {
  /**
   * A globally-unique identifier.
   */
  id: string;

  /**
   * The product’s vendor name.
   */
  vendor: string;

  /**
   * A categorization that a product can be tagged with, commonly used for filtering and searching.
   */
  productType: string;
}
The product object that the product variant belongs to.

### requiresShipping

value: `boolean`

Whether or not the product requires shipping.

### sellingPlan

value: `SellingPlan`

  - SellingPlan: export interface SellingPlan {
  /**
   * A globally-unique identifier.
   * @example 'gid://shopify/SellingPlan/1'
   */
  id: string;
}
The selling plan associated with the merchandise.

### ImageDetails

### url

value: `string`

The image URL.

### altText

value: `string`

The alternative text for the image.

### SelectedOption

### name

value: `string`

The name of the merchandise option.

### value

value: `string`

The value of the merchandise option.

### Product

### id

value: `string`

A globally-unique identifier.

### vendor

value: `string`

The product’s vendor name.

### productType

value: `string`

A categorization that a product can be tagged with, commonly used for filtering and searching.

### SellingPlan

### id

value: `string`

A globally-unique identifier.

### CartLineCost

### totalAmount

value: `Money`

  - Money: export interface Money {
  /**
   * The price amount.
   */
  amount: number;
  /**
   * The ISO 4217 format for the currency.
   * @example 'CAD' for Canadian dollar
   */
  currencyCode: CurrencyCode;
}
The total amount after reductions the buyer can expect to pay that is directly attributable to a single
cart line.

### Money

### amount

value: `number`

The price amount.

### currencyCode

value: `CurrencyCode`

  - CurrencyCode: 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL'
The ISO 4217 format for the currency.

### CartCodeDiscountAllocation

### code

value: `string`

The code for the discount

### type

value: `"code"`

The type of the code discount

### discountedAmount

value: `Money`

  - Money: export interface Money {
  /**
   * The price amount.
   */
  amount: number;
  /**
   * The ISO 4217 format for the currency.
   * @example 'CAD' for Canadian dollar
   */
  currencyCode: CurrencyCode;
}
The money amount that has been discounted from the order

### CartAutomaticDiscountAllocation

### title

value: `string`

The title of the automatic discount

### type

value: `"automatic"`

The type of the automatic discount

### discountedAmount

value: `Money`

  - Money: export interface Money {
  /**
   * The price amount.
   */
  amount: number;
  /**
   * The ISO 4217 format for the currency.
   * @example 'CAD' for Canadian dollar
   */
  currencyCode: CurrencyCode;
}
The money amount that has been discounted from the order

### CartCustomDiscountAllocation

### title

value: `string`

The title of the custom discount

### type

value: `"custom"`

The type of the custom discount

### discountedAmount

value: `Money`

  - Money: export interface Money {
  /**
   * The price amount.
   */
  amount: number;
  /**
   * The ISO 4217 format for the currency.
   * @example 'CAD' for Canadian dollar
   */
  currencyCode: CurrencyCode;
}
The money amount that has been discounted from the order

### CartBundleLineComponent

### type

value: `"bundle"`


### id

value: `string`

A unique identifier for the bundle line component.

This ID is not stable. If an operation updates the line items in any way, all IDs could change.

### merchandise

value: `Merchandise`

  - Merchandise: ProductVariant
The merchandise of this bundle line component.

### quantity

value: `number`

The quantity of merchandise being purchased.

### cost

value: `CartLineCost`

  - CartLine: export interface CartLine {
  /**
   * These line item IDs are not stable at the moment, they might change after
   * any operations on the line items. You should always look up for an updated
   * ID before any call to `applyCartLinesChange` because you'll need the ID to
   * create a `CartLineChange` object.
   * @example 'gid://shopify/CartLine/123'
   */
  id: string;

  /**
   * The merchandise being purchased.
   */
  merchandise: Merchandise;

  /**
   * The quantity of the merchandise being purchased.
   */
  quantity: number;

  /**
   * The details about the cost components attributed to the cart line.
   */
  cost: CartLineCost;

  /**
   * The line item additional custom attributes.
   */
  attributes: Attribute[];

  /**
   * Discounts applied to the cart line.
   */
  discountAllocations: CartDiscountAllocation[];

  /**
   * Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.
   */
  lineComponents: CartLineComponentType[];
}
  - CartLineCost: export interface CartLineCost {
  /**
   * The total amount after reductions the buyer can expect to pay that is directly attributable to a single
   * cart line.
   */
  totalAmount: Money;
}
The cost attributed to this bundle line component.

### attributes

value: `Attribute[]`

  - Attribute: export interface Attribute {
  /**
   * The key for the attribute.
   */
  key: string;

  /**
   * The value for the attribute.
   */
  value: string;
}
Additional custom attributes for the bundle line component.

### CartLineRemoveChange

### type

value: `"removeCartLine"`

  - CartLine: export interface CartLine {
  /**
   * These line item IDs are not stable at the moment, they might change after
   * any operations on the line items. You should always look up for an updated
   * ID before any call to `applyCartLinesChange` because you'll need the ID to
   * create a `CartLineChange` object.
   * @example 'gid://shopify/CartLine/123'
   */
  id: string;

  /**
   * The merchandise being purchased.
   */
  merchandise: Merchandise;

  /**
   * The quantity of the merchandise being purchased.
   */
  quantity: number;

  /**
   * The details about the cost components attributed to the cart line.
   */
  cost: CartLineCost;

  /**
   * The line item additional custom attributes.
   */
  attributes: Attribute[];

  /**
   * Discounts applied to the cart line.
   */
  discountAllocations: CartDiscountAllocation[];

  /**
   * Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.
   */
  lineComponents: CartLineComponentType[];
}
An identifier for changes that remove line items.

### id

value: `string`

Line Item ID.

### quantity

value: `number`

The quantity being removed for this line item.

### CartLineUpdateChange

### type

value: `"updateCartLine"`

  - CartLine: export interface CartLine {
  /**
   * These line item IDs are not stable at the moment, they might change after
   * any operations on the line items. You should always look up for an updated
   * ID before any call to `applyCartLinesChange` because you'll need the ID to
   * create a `CartLineChange` object.
   * @example 'gid://shopify/CartLine/123'
   */
  id: string;

  /**
   * The merchandise being purchased.
   */
  merchandise: Merchandise;

  /**
   * The quantity of the merchandise being purchased.
   */
  quantity: number;

  /**
   * The details about the cost components attributed to the cart line.
   */
  cost: CartLineCost;

  /**
   * The line item additional custom attributes.
   */
  attributes: Attribute[];

  /**
   * Discounts applied to the cart line.
   */
  discountAllocations: CartDiscountAllocation[];

  /**
   * Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.
   */
  lineComponents: CartLineComponentType[];
}
An identifier for changes that update line items.

### id

value: `string`

Line Item ID.

### merchandiseId

value: `string`

The new merchandise ID for the line item.

### quantity

value: `number`

The new quantity for the line item.

### attributes

value: `Attribute[]`

  - Attribute: export interface Attribute {
  /**
   * The key for the attribute.
   */
  key: string;

  /**
   * The value for the attribute.
   */
  value: string;
}
The new attributes for the line item.

### sellingPlanId

value: `string`

The identifier of the selling plan that the merchandise is being purchased
with or `null` to remove the the product from the selling plan.

### CartLineChangeResultSuccess

### type

value: `"success"`

Indicates that the line item was changed successfully.

### CartLineChangeResultError

### type

value: `"error"`

Indicates that the line item was not changed successfully. Refer to the `message` property for details about the error.

### message

value: `string`

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.

### DiscountCodeAddChange

### type

value: `"addDiscountCode"`

The type of the `DiscountCodeChange` API.

### code

value: `string`

The code for the discount

### DiscountCodeRemoveChange

### type

value: `"removeDiscountCode"`

The type of the `DiscountCodeChange` API.

### code

value: `string`

The code for the discount

### DiscountCodeChangeResultSuccess

### type

value: `"success"`

Indicates that the discount code change was applied successfully.

### DiscountCodeChangeResultError

### type

value: `"error"`

Indicates that the discount code change failed.

### message

value: `string`

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.

### GiftCardAddChange

### type

value: `"addGiftCard"`

The type of the `GiftCardChange` API.

### code

value: `string`

Gift card code.

### GiftCardRemoveChange

### type

value: `"removeGiftCard"`

The type of the `GiftCardChange` API.

### code

value: `string`

Gift card code.

### GiftCardChangeResultSuccess

### type

value: `"success"`

Indicates that the gift card change was applied successfully.

### GiftCardChangeResultError

### type

value: `"error"`

Indicates that the gift card change failed.

### message

value: `string`

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.

### MetafieldRemoveChange

Removes a metafield.

### type

value: `"removeMetafield"`

  - Metafield: export interface Metafield {
  /**
   * The name of the metafield. It must be between 3 and 30 characters in
   * length (inclusive).
   */
  key: string;

  /**
   * A container for a set of metafields. You need to define a custom
   * namespace for your metafields to distinguish them from the metafields
   * used by other apps. This must be between 2 and 20 characters in length (inclusive).
   */
  namespace: string;

  /**
   * The information to be stored as metadata.
   */
  value: string | number;

  /** The metafield’s information type. */
  valueType: 'integer' | 'string' | 'json_string';
}
The type of the `MetafieldRemoveChange` API.

### key

value: `string`

The name of the metafield to remove.

### namespace

value: `string`

The namespace of the metafield to remove.

### Metafield

Metadata associated with the checkout.

### key

value: `string`

The name of the metafield. It must be between 3 and 30 characters in
length (inclusive).

### namespace

value: `string`

A container for a set of metafields. You need to define a custom
namespace for your metafields to distinguish them from the metafields
used by other apps. This must be between 2 and 20 characters in length (inclusive).

### value

value: `string | number`

The information to be stored as metadata.

### valueType

value: `"string" | "integer" | "json_string"`

The metafield’s information type.

### MetafieldUpdateChange

Updates a metafield. If a metafield with the
provided key and namespace does not already exist, it gets created.

### type

value: `"updateMetafield"`

  - Metafield: export interface Metafield {
  /**
   * The name of the metafield. It must be between 3 and 30 characters in
   * length (inclusive).
   */
  key: string;

  /**
   * A container for a set of metafields. You need to define a custom
   * namespace for your metafields to distinguish them from the metafields
   * used by other apps. This must be between 2 and 20 characters in length (inclusive).
   */
  namespace: string;

  /**
   * The information to be stored as metadata.
   */
  value: string | number;

  /** The metafield’s information type. */
  valueType: 'integer' | 'string' | 'json_string';
}
The type of the `MetafieldUpdateChange` API.

### key

value: `string`

The name of the metafield to update.

### namespace

value: `string`

The namespace of the metafield to add.

### value

value: `string | number`

The new information to store in the metafield.

### valueType

value: `"string" | "integer" | "json_string"`

The metafield’s information type.

### MetafieldRemoveCartChange

Removes a cart metafield.

### type

value: `"removeCartMetafield"`

  - Metafield: export interface Metafield {
  /**
   * The name of the metafield. It must be between 3 and 30 characters in
   * length (inclusive).
   */
  key: string;

  /**
   * A container for a set of metafields. You need to define a custom
   * namespace for your metafields to distinguish them from the metafields
   * used by other apps. This must be between 2 and 20 characters in length (inclusive).
   */
  namespace: string;

  /**
   * The information to be stored as metadata.
   */
  value: string | number;

  /** The metafield’s information type. */
  valueType: 'integer' | 'string' | 'json_string';
}
  - CartMetafield: export interface CartMetafield {
  /** The key name of a metafield. */
  key: string;

  /** The namespace for a metafield. */
  namespace: string;

  /** The value of a metafield. */
  value: string;

  /** The metafield's type name. */
  type: string;
}
The type of the `MetafieldRemoveChange` API.

### key

value: `string`

The name of the metafield to remove.

### namespace

value: `string`

The namespace of the metafield to remove.

### CartMetafield

Represents a custom metadata attached to a resource.

### key

value: `string`

The key name of a metafield.

### namespace

value: `string`

The namespace for a metafield.

### value

value: `string`

The value of a metafield.

### type

value: `string`

The metafield's type name.

### MetafieldUpdateCartChange

Updates a cart metafield. If a metafield with the
provided key and namespace does not already exist, it gets created.

### type

value: `"updateCartMetafield"`

  - Metafield: export interface Metafield {
  /**
   * The name of the metafield. It must be between 3 and 30 characters in
   * length (inclusive).
   */
  key: string;

  /**
   * A container for a set of metafields. You need to define a custom
   * namespace for your metafields to distinguish them from the metafields
   * used by other apps. This must be between 2 and 20 characters in length (inclusive).
   */
  namespace: string;

  /**
   * The information to be stored as metadata.
   */
  value: string | number;

  /** The metafield’s information type. */
  valueType: 'integer' | 'string' | 'json_string';
}
  - CartMetafield: export interface CartMetafield {
  /** The key name of a metafield. */
  key: string;

  /** The namespace for a metafield. */
  namespace: string;

  /** The value of a metafield. */
  value: string;

  /** The metafield's type name. */
  type: string;
}
The type of the `MetafieldUpdateChange` API.

### metafield

value: `{ key: string; namespace: string; value: string; type: string; }`


### MetafieldChangeResultSuccess

### type

value: `"success"`

The type of the `MetafieldChangeResultSuccess` API.

### MetafieldChangeResultError

### type

value: `"error"`

The type of the `MetafieldChangeResultError` API.

### message

value: `string`

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.

### NoteRemoveChange

Removes a note

### type

value: `"removeNote"`

The type of the `NoteRemoveChange` API.

### NoteUpdateChange

An Update to a note on the order.
for example, the buyer could request detailed packaging instructions in an order note

### type

value: `"updateNote"`

The type of the `NoteUpdateChange` API.

### note

value: `string`

The new value of the note.

### NoteChangeResultSuccess

### type

value: `"success"`

The type of the `NoteChangeResultSuccess` API.

### NoteChangeResultError

### type

value: `"error"`

The type of the `NoteChangeResultError` API.

### message

value: `string`

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.

### ShippingAddressUpdateChange

### type

value: `"updateShippingAddress"`

The type of the `ShippingAddressUpdateChange` API.

### address

value: `Partial<MailingAddress>`

  - MailingAddress: export interface MailingAddress {
  /**
   * The buyer's full name.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'John Doe'
   */
  name?: string;

  /**
   * The buyer's first name.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'John'
   */
  firstName?: string;

  /**
   * The buyer's last name.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'Doe'
   */
  lastName?: string;

  /**
   * The buyer's company name.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'Shopify'
   */
  company?: string;

  /**
   * The first line of the buyer's address, including street name and number.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example '151 O'Connor Street'
   */
  address1?: string;

  /**
   * The second line of the buyer's address, like apartment number, suite, etc.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'Ground floor'
   */
  address2?: string;

  /**
   * The buyer's city.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'Ottawa'
   */
  city?: string;

  /**
   * The buyer's postal or ZIP code.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'K2P 2L8'
   */
  zip?: string;

  /**
   * The ISO 3166 Alpha-2 format for the buyer's country. Refer to https://www.iso.org/iso-3166-country-codes.html.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'CA' for Canada.
   */
  countryCode?: CountryCode;

  /**
   * The buyer's province code, such as state, province, prefecture, or region.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'ON' for Ontario.
   */
  provinceCode?: string;

  /**
   * The buyer's phone number.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example '+1 613 111 2222'.
   */
  phone?: string;
}
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.

### MailingAddress

### name

value: `string`

The buyer's full name.

{% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).

### firstName

value: `string`

The buyer's first name.

{% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).

### lastName

value: `string`

The buyer's last name.

{% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).

### company

value: `string`

The buyer's company name.

{% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).

### address1

value: `string`

The first line of the buyer's address, including street name and number.

{% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).

### address2

value: `string`

The second line of the buyer's address, like apartment number, suite, etc.

{% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).

### city

value: `string`

The buyer's city.

{% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).

### zip

value: `string`

The buyer's postal or ZIP code.

{% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).

### countryCode

value: `CountryCode`

  - CountryCode: 'AC' | 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AN' | 'AO' | 'AR' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PS' | 'PT' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TA' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VN' | 'VU' | 'WF' | 'WS' | 'XK' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' | 'ZZ'
The ISO 3166 Alpha-2 format for the buyer's country. Refer to https://www.iso.org/iso-3166-country-codes.html.

{% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).

### provinceCode

value: `string`

The buyer's province code, such as state, province, prefecture, or region.

{% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).

### phone

value: `string`

The buyer's phone number.

{% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).

### ShippingAddressChangeResultSuccess

The returned result of a successful update to the shipping address.

### type

value: `"success"`

The type of the `ShippingAddressChangeResultSuccess` API.

### errors

value: `null`


### ShippingAddressChangeResultError

The returned result of an update to the shipping address
with a messages detailing the type of errors that occurred.

### type

value: `"error"`

The type of the `ShippingAddressChangeResultError` API.

### errors

value: `ShippingAddressChangeFieldError[]`

  - ShippingAddressChangeFieldError: export interface ShippingAddressChangeFieldError {
  /**
   * field key from MailingAddress where the error occurred
   */
  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.
   */
  message: string;
}
The errors corresponding to particular fields from a given change

### ShippingAddressChangeFieldError

An error corresponding to a particular field from a given change

### field

value: `keyof MailingAddress`

  - MailingAddress: export interface MailingAddress {
  /**
   * The buyer's full name.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'John Doe'
   */
  name?: string;

  /**
   * The buyer's first name.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'John'
   */
  firstName?: string;

  /**
   * The buyer's last name.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'Doe'
   */
  lastName?: string;

  /**
   * The buyer's company name.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'Shopify'
   */
  company?: string;

  /**
   * The first line of the buyer's address, including street name and number.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example '151 O'Connor Street'
   */
  address1?: string;

  /**
   * The second line of the buyer's address, like apartment number, suite, etc.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'Ground floor'
   */
  address2?: string;

  /**
   * The buyer's city.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'Ottawa'
   */
  city?: string;

  /**
   * The buyer's postal or ZIP code.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'K2P 2L8'
   */
  zip?: string;

  /**
   * The ISO 3166 Alpha-2 format for the buyer's country. Refer to https://www.iso.org/iso-3166-country-codes.html.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'CA' for Canada.
   */
  countryCode?: CountryCode;

  /**
   * The buyer's province code, such as state, province, prefecture, or region.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example 'ON' for Ontario.
   */
  provinceCode?: string;

  /**
   * The buyer's phone number.
   *
   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
   *
   * @example '+1 613 111 2222'.
   */
  phone?: string;
}
field key from MailingAddress where the error occurred

### message

value: `string`

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.

## Related

- [StandardApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi)
- [OrderStatusApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/orderstatusapi)
- [CartLineItemApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cartlineitemapi)
- [PickupPointListApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuppointlistapi)
- [PickupLocationListApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuplocationlistapi)
- [ShippingOptionItemApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/shippingoptionitemapi)
- [ExtensionTargets](https://shopify.dev/docs/api/checkout-ui-extensions/apis/extensiontargets)