--- 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]\(/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\** **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\** **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\** **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\ 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\** **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\ 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\** **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\** **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\** 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 ``` ### AttributeChangeResult ```ts AttributeChangeResultSuccess | AttributeChangeResultError ``` ### AttributeChangeResultSuccess The returned result of a successful update to an attribute. * type The type of the \`AttributeChangeResultSuccess\` API. ```ts "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 ``` ### 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 ``` ### Attribute * key The key for the attribute. ```ts string ``` * value The value for the attribute. ```ts 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 ``` ### 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 ``` ### CartLineChangeResult ```ts CartLineChangeResultSuccess | CartLineChangeResultError ``` ### CartLineChangeResultSuccess * type Indicates that the line item was changed successfully. ```ts "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 ``` ### DiscountCodeChange ```ts DiscountCodeAddChange | DiscountCodeRemoveChange ``` ### DiscountCodeAddChange * type The type of the \`DiscountCodeChange\` API. ```ts "addDiscountCode" ``` * code The code for the discount ```ts string ``` ### DiscountCodeRemoveChange * type The type of the \`DiscountCodeChange\` API. ```ts "removeDiscountCode" ``` * code The code for the discount ```ts string ``` ### DiscountCodeChangeResult ```ts DiscountCodeChangeResultSuccess | DiscountCodeChangeResultError ``` ### DiscountCodeChangeResultSuccess * type Indicates that the discount code change was applied successfully. ```ts "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 ``` ### GiftCardChange ```ts GiftCardAddChange | GiftCardRemoveChange ``` ### GiftCardAddChange * type The type of the \`GiftCardChange\` API. ```ts "addGiftCard" ``` * code Gift card code. ```ts string ``` ### GiftCardRemoveChange * type The type of the \`GiftCardChange\` API. ```ts "removeGiftCard" ``` * code Gift card code. ```ts string ``` ### GiftCardChangeResult ```ts GiftCardChangeResultSuccess | GiftCardChangeResultError ``` ### GiftCardChangeResultSuccess * type Indicates that the gift card change was applied successfully. ```ts "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 ``` ### 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 ``` ### 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" ``` ### 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 ``` ### 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; } ``` ### MetafieldChangeResult ```ts MetafieldChangeResultSuccess | MetafieldChangeResultError ``` ### MetafieldChangeResultSuccess * type The type of the \`MetafieldChangeResultSuccess\` API. ```ts "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 ``` ### NoteChange ```ts NoteRemoveChange | NoteUpdateChange ``` ### NoteRemoveChange Removes a note * type The type of the \`NoteRemoveChange\` API. ```ts "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 ``` ### NoteChangeResult ```ts NoteChangeResultSuccess | NoteChangeResultError ``` ### NoteChangeResultSuccess * type The type of the \`NoteChangeResultSuccess\` API. ```ts "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 ``` ### 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 * 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 ``` ### 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 ``` ### 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[] ``` ### 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 ``` Examples ### 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', () => , ); function Extension() { const applyAttributeChange = useApplyAttributeChange(); // 2. Render a UI return ( 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 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 [APIs - StandardApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi) [APIs - OrderStatusApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/orderstatusapi) [APIs - CartLineItemApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cartlineitemapi) [APIs - PickupPointListApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuppointlistapi) [APIs - PickupLocationListApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuplocationlistapi) [APIs - ShippingOptionItemApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/shippingoptionitemapi) [APIs - ExtensionTargets](https://shopify.dev/docs/api/checkout-ui-extensions/apis/extensiontargets)