---
title: CheckoutApi
description: |
  
  This API object is provided to extensions registered for the extension targets that appear exclusively pre-purchase.

  It extends the [StandardApi](/docs/api/checkout-ui-extensions/apis/standardapi) and provides the write apis for the checkout data.
api_version: 2023-07
api_name: checkout-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/checkout-ui-extensions/2023-07/apis/checkoutapi
  md: https://shopify.dev/docs/api/checkout-ui-extensions/2023-07/apis/checkoutapi.md
---

# Checkout​Api

Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) for some properties.

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.

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

* applyAttributeChange

  (change: AttributeUpdateChange) => Promise\<AttributeChangeResult>

  required

  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

  (change: CartLineChange) => Promise\<CartLineChangeResult>

  required

  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

  (change: DiscountCodeChange) => Promise\<DiscountCodeChangeResult>

  required

  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

  (change: GiftCardChange) => Promise\<GiftCardChangeResult>

  required

  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

  (change: MetafieldChange) => Promise\<MetafieldChangeResult>

  required

  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

  (change: NoteChange) => Promise\<NoteChangeResult>

  required

  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.

* applyShippingAddressChange

  (change: ShippingAddressUpdateChange) => Promise\<ShippingAddressChangeResult>

  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.

  [](https://shopify.dev/apps/store/data-protection/protected-customer-data)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

  The type of the \`AttributeUpdateChange\` API.

  ```ts
  "updateAttribute"
  ```

* key

  Key of the attribute to add or update

  ```ts
  string
  ```

* value

  Value for the attribute to add or update

  ```ts
  string
  ```

```ts
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;
}
```

### AttributeChangeResult

```ts
AttributeChangeResultSuccess | AttributeChangeResultError
```

### AttributeChangeResultSuccess

The returned result of a successful update to an attribute.

* type

  The type of the \`AttributeChangeResultSuccess\` API.

  ```ts
  "success"
  ```

```ts
export interface AttributeChangeResultSuccess {
  /**
   * The type of the `AttributeChangeResultSuccess` API.
   */
  type: 'success';
}
```

### AttributeChangeResultError

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

* type

  The type of the \`AttributeChangeResultError\` API.

  ```ts
  "error"
  ```

* message

  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.

  ```ts
  string
  ```

```ts
export interface AttributeChangeResultError {
  /**
   * The type of the `AttributeChangeResultError` API.
   */
  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.
   */
  message: string;
}
```

### CartLineChange

```ts
CartLineAddChange | CartLineRemoveChange | CartLineUpdateChange
```

### CartLineAddChange

* type

  An identifier for changes that add line items.

  ```ts
  "addCartLine"
  ```

* merchandiseId

  The merchandise ID being added.

  ```ts
  string
  ```

* quantity

  The quantity of the merchandise being added.

  ```ts
  number
  ```

* attributes

  The attributes associated with the line item.

  ```ts
  Attribute[]
  ```

* sellingPlanId

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

  ```ts
  string
  ```

```ts
export interface CartLineAddChange {
  /**
   * An identifier for changes that add line items.
   */
  type: 'addCartLine';

  /**
   * The merchandise ID being added.
   * @example 'gid://shopify/ProductVariant/123'
   */
  merchandiseId: string;

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

  /**
   * The attributes associated with the line item.
   */
  attributes?: Attribute[];

  /**
   * The identifier of the selling plan that the merchandise is being purchased
   * with.
   */
  sellingPlanId?: SellingPlan['id'];
}
```

### Attribute

* key

  The key for the attribute.

  ```ts
  string
  ```

* value

  The value for the attribute.

  ```ts
  string
  ```

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

  /**
   * The value for the attribute.
   */
  value: string;
}
```

### CartLineRemoveChange

* type

  An identifier for changes that remove line items.

  ```ts
  "removeCartLine"
  ```

* id

  Line Item ID.

  ```ts
  string
  ```

* quantity

  The quantity being removed for this line item.

  ```ts
  number
  ```

```ts
export interface CartLineRemoveChange {
  /**
   * An identifier for changes that remove line items.
   */
  type: 'removeCartLine';

  /**
   * Line Item ID.
   * @example 'gid://shopify/CartLine/123'
   */
  id: string;

  /**
   * The quantity being removed for this line item.
   */
  quantity: number;
}
```

### CartLineUpdateChange

* type

  An identifier for changes that update line items.

  ```ts
  "updateCartLine"
  ```

* id

  Line Item ID.

  ```ts
  string
  ```

* merchandiseId

  The new merchandise ID for the line item.

  ```ts
  string
  ```

* quantity

  The new quantity for the line item.

  ```ts
  number
  ```

* attributes

  The new attributes for the line item.

  ```ts
  Attribute[]
  ```

* sellingPlanId

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

  ```ts
  string
  ```

```ts
export interface CartLineUpdateChange {
  /**
   * An identifier for changes that update line items.
   */
  type: 'updateCartLine';

  /**
   * Line Item ID.
   * @example 'gid://shopify/CartLine/123'
   */
  id: string;

  /**
   * The new merchandise ID for the line item.
   * @example 'gid://shopify/ProductVariant/123'
   */

  merchandiseId?: string;
  /**
   * The new quantity for the line item.
   */
  quantity?: number;

  /**
   * The new attributes for the line item.
   */
  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.
   */
  sellingPlanId?: SellingPlan['id'] | null;
}
```

### CartLineChangeResult

```ts
CartLineChangeResultSuccess | CartLineChangeResultError
```

### CartLineChangeResultSuccess

* type

  Indicates that the line item was changed successfully.

  ```ts
  "success"
  ```

```ts
export interface CartLineChangeResultSuccess {
  /**
   * Indicates that the line item was changed successfully.
   */
  type: 'success';
}
```

### CartLineChangeResultError

* type

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

  ```ts
  "error"
  ```

* message

  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.

  ```ts
  string
  ```

```ts
export interface CartLineChangeResultError {
  /**
   * Indicates that the line item was not 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
   * to the buyer.
   */
  message: string;
}
```

### DiscountCodeChange

```ts
DiscountCodeAddChange | DiscountCodeRemoveChange
```

### DiscountCodeAddChange

* type

  The type of the \`DiscountCodeChange\` API.

  ```ts
  "addDiscountCode"
  ```

* code

  The code for the discount

  ```ts
  string
  ```

```ts
export interface DiscountCodeAddChange {
  /**
   * The type of the `DiscountCodeChange` API.
   */
  type: 'addDiscountCode';

  /**
   * The code for the discount
   */
  code: string;
}
```

### DiscountCodeRemoveChange

* type

  The type of the \`DiscountCodeChange\` API.

  ```ts
  "removeDiscountCode"
  ```

* code

  The code for the discount

  ```ts
  string
  ```

```ts
export interface DiscountCodeRemoveChange {
  /**
   * The type of the `DiscountCodeChange` API.
   */
  type: 'removeDiscountCode';

  /**
   * The code for the discount
   */
  code: string;
}
```

### DiscountCodeChangeResult

```ts
DiscountCodeChangeResultSuccess | DiscountCodeChangeResultError
```

### DiscountCodeChangeResultSuccess

* type

  Indicates that the discount code change was applied successfully.

  ```ts
  "success"
  ```

```ts
export interface DiscountCodeChangeResultSuccess {
  /**
   * Indicates that the discount code change was applied successfully.
   */
  type: 'success';
}
```

### DiscountCodeChangeResultError

* type

  Indicates that the discount code change failed.

  ```ts
  "error"
  ```

* message

  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.

  ```ts
  string
  ```

```ts
export interface DiscountCodeChangeResultError {
  /**
   * Indicates that the discount code change failed.
   */
  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.
   */
  message: string;
}
```

### GiftCardChange

```ts
GiftCardAddChange | GiftCardRemoveChange
```

### GiftCardAddChange

* type

  The type of the \`GiftCardChange\` API.

  ```ts
  "addGiftCard"
  ```

* code

  Gift card code.

  ```ts
  string
  ```

```ts
export interface GiftCardAddChange {
  /**
   * The type of the `GiftCardChange` API.
   */
  type: 'addGiftCard';

  /**
   * Gift card code.
   */
  code: string;
}
```

### GiftCardRemoveChange

* type

  The type of the \`GiftCardChange\` API.

  ```ts
  "removeGiftCard"
  ```

* code

  Gift card code.

  ```ts
  string
  ```

```ts
export interface GiftCardRemoveChange {
  /**
   * The type of the `GiftCardChange` API.
   */
  type: 'removeGiftCard';

  /**
   * Gift card code.
   */
  code: string;
}
```

### GiftCardChangeResult

```ts
GiftCardChangeResultSuccess | GiftCardChangeResultError
```

### GiftCardChangeResultSuccess

* type

  Indicates that the gift card change was applied successfully.

  ```ts
  "success"
  ```

```ts
export interface GiftCardChangeResultSuccess {
  /**
   * Indicates that the gift card change was applied successfully.
   */
  type: 'success';
}
```

### GiftCardChangeResultError

* type

  Indicates that the gift card change failed.

  ```ts
  "error"
  ```

* message

  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.

  ```ts
  string
  ```

```ts
export interface GiftCardChangeResultError {
  /**
   * Indicates that the gift card change failed.
   */
  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.
   */
  message: string;
}
```

### MetafieldChange

```ts
MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange
```

### MetafieldRemoveChange

Removes a metafield.

* type

  The type of the \`MetafieldRemoveChange\` API.

  ```ts
  "removeMetafield"
  ```

* key

  The name of the metafield to remove.

  ```ts
  string
  ```

* namespace

  The namespace of the metafield to remove.

  ```ts
  string
  ```

```ts
export interface MetafieldRemoveChange {
  /**
   * The type of the `MetafieldRemoveChange` API.
   */
  type: 'removeMetafield';

  /**
   * The name of the metafield to remove.
   */
  key: string;

  /**
   * The namespace of the metafield to remove.
   */
  namespace: string;
}
```

### MetafieldUpdateChange

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

* type

  The type of the \`MetafieldUpdateChange\` API.

  ```ts
  "updateMetafield"
  ```

* key

  The name of the metafield to update.

  ```ts
  string
  ```

* namespace

  The namespace of the metafield to add.

  ```ts
  string
  ```

* value

  The new information to store in the metafield.

  ```ts
  string | number
  ```

* valueType

  The metafield’s information type.

  ```ts
  "string" | "integer" | "json_string"
  ```

```ts
export interface MetafieldUpdateChange {
  /**
   * The type of the `MetafieldUpdateChange` API.
   */
  type: 'updateMetafield';

  /** The name of the metafield to update. */
  key: string;

  /** The namespace of the metafield to add. */
  namespace: string;

  /** The new information to store in the metafield. */
  value: string | number;

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

### MetafieldRemoveCartChange

Removes a cart metafield.

* type

  The type of the \`MetafieldRemoveChange\` API.

  ```ts
  "removeCartMetafield"
  ```

* key

  The name of the metafield to remove.

  ```ts
  string
  ```

* namespace

  The namespace of the metafield to remove.

  ```ts
  string
  ```

```ts
export interface MetafieldRemoveCartChange {
  /**
   * The type of the `MetafieldRemoveChange` API.
   */
  type: 'removeCartMetafield';

  /**
   * The name of the metafield to remove.
   */
  key: string;

  /**
   * The namespace of the metafield to remove.
   */
  namespace: string;
}
```

### MetafieldUpdateCartChange

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

* type

  The type of the \`MetafieldUpdateChange\` API.

  ```ts
  "updateCartMetafield"
  ```

* metafield

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

```ts
export interface MetafieldUpdateCartChange {
  /**
   * The type of the `MetafieldUpdateChange` API.
   */
  type: 'updateCartMetafield';

  metafield: {
    /** The name of the metafield to update. */
    key: string;

    /** The namespace of the metafield to add. */
    namespace: string;

    /** The new information to store in the metafield. */
    value: string;

    /**
     * The metafield’s information type.
     * See the [`metafields documentation`](/docs/apps/custom-data/metafields/types) for a list of supported types.
     */
    type: string;
  };
}
```

### MetafieldChangeResult

```ts
MetafieldChangeResultSuccess | MetafieldChangeResultError
```

### MetafieldChangeResultSuccess

* type

  The type of the \`MetafieldChangeResultSuccess\` API.

  ```ts
  "success"
  ```

```ts
export interface MetafieldChangeResultSuccess {
  /**
   * The type of the `MetafieldChangeResultSuccess` API.
   */
  type: 'success';
}
```

### MetafieldChangeResultError

* type

  The type of the \`MetafieldChangeResultError\` API.

  ```ts
  "error"
  ```

* message

  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.

  ```ts
  string
  ```

```ts
export interface MetafieldChangeResultError {
  /**
   * The type of the `MetafieldChangeResultError` API.
   */
  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.
   */
  message: string;
}
```

### NoteChange

```ts
NoteRemoveChange | NoteUpdateChange
```

### NoteRemoveChange

Removes a note

* type

  The type of the \`NoteRemoveChange\` API.

  ```ts
  "removeNote"
  ```

```ts
export interface NoteRemoveChange {
  /**
   * The type of the `NoteRemoveChange` API.
   */
  type: 'removeNote';
}
```

### NoteUpdateChange

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

* type

  The type of the \`NoteUpdateChange\` API.

  ```ts
  "updateNote"
  ```

* note

  The new value of the note.

  ```ts
  string
  ```

```ts
export interface NoteUpdateChange {
  /**
   * The type of the `NoteUpdateChange` API.
   */
  type: 'updateNote';
  /**
   * The new value of the note.
   */
  note: string;
}
```

### NoteChangeResult

```ts
NoteChangeResultSuccess | NoteChangeResultError
```

### NoteChangeResultSuccess

* type

  The type of the \`NoteChangeResultSuccess\` API.

  ```ts
  "success"
  ```

```ts
export interface NoteChangeResultSuccess {
  /**
   * The type of the `NoteChangeResultSuccess` API.
   */
  type: 'success';
}
```

### NoteChangeResultError

* type

  The type of the \`NoteChangeResultError\` API.

  ```ts
  "error"
  ```

* message

  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.

  ```ts
  string
  ```

```ts
export interface NoteChangeResultError {
  /**
   * The type of the `NoteChangeResultError` API.
   */
  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.
   */
  message: string;
}
```

### ShippingAddressUpdateChange

* type

  The type of the \`ShippingAddressUpdateChange\` API.

  ```ts
  "updateShippingAddress"
  ```

* address

  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.

  ```ts
  Partial<MailingAddress>
  ```

```ts
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>;
}
```

### MailingAddress

* name

  The buyer's full name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data).

  ```ts
  string
  ```

* firstName

  The buyer's first name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data).

  ```ts
  string
  ```

* lastName

  The buyer's last name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data).

  ```ts
  string
  ```

* company

  The buyer's company name. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data).

  ```ts
  string
  ```

* address1

  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]\(/docs/apps/store/data-protection/protected-customer-data).

  ```ts
  string
  ```

* address2

  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]\(/docs/apps/store/data-protection/protected-customer-data).

  ```ts
  string
  ```

* city

  The buyer's city. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data).

  ```ts
  string
  ```

* zip

  The buyer's postal or ZIP code. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data).

  ```ts
  string
  ```

* countryCode

  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]\(/docs/apps/store/data-protection/protected-customer-data).

  ```ts
  CountryCode
  ```

* provinceCode

  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]\(/docs/apps/store/data-protection/protected-customer-data).

  ```ts
  string
  ```

* phone

  The buyer's phone number. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data).

  ```ts
  string
  ```

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

### CountryCode

```ts
'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'
```

### ShippingAddressChangeResult

```ts
ShippingAddressChangeResultSuccess | ShippingAddressChangeResultError
```

### ShippingAddressChangeResultSuccess

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

* type

  The type of the \`ShippingAddressChangeResultSuccess\` API.

  ```ts
  "success"
  ```

* errors

  ```ts
  null
  ```

```ts
export interface ShippingAddressChangeResultSuccess {
  /**
   * The type of the `ShippingAddressChangeResultSuccess` API.
   */
  type: 'success';

  errors: null;
}
```

### ShippingAddressChangeResultError

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

* type

  The type of the \`ShippingAddressChangeResultError\` API.

  ```ts
  "error"
  ```

* errors

  The errors corresponding to particular fields from a given change

  ```ts
  ShippingAddressChangeFieldError[]
  ```

```ts
export interface ShippingAddressChangeResultError {
  /**
   * The type of the `ShippingAddressChangeResultError` API.
   */
  type: 'error';

  /**
   * The errors corresponding to particular fields from a given change
   */
  errors: ShippingAddressChangeFieldError[];
}
```

### ShippingAddressChangeFieldError

An error corresponding to a particular field from a given change

* field

  field key from MailingAddress where the error occurred

  ```ts
  keyof MailingAddress
  ```

* message

  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.

  ```ts
  string
  ```

```ts
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;
}
```

### Examples

* ####

  ##### React

  ```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,
      );
    }
  }
  ```

  ##### JavaScript

  ```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,
        );
      }
    },
  );
  ```

## Related

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi)

[APIsStandardApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/orderstatusapi)

[APIsOrderStatusApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/orderstatusapi)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cartlineitemapi)

[APIsCartLineItemApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cartlineitemapi)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuppointlistapi)

[APIsPickupPointListApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuppointlistapi)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuplocationlistapi)

[APIsPickupLocationListApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuplocationlistapi)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/shippingoptionitemapi)

[APIsShippingOptionItemApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/shippingoptionitemapi)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/extensiontargets)

[APIsExtensionTargets](https://shopify.dev/docs/api/checkout-ui-extensions/apis/extensiontargets)