--- title: CheckoutApi description: > This API object is provided to extensions registered for the extension points 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-04 api_name: checkout-ui-extensions source_url: html: 'https://shopify.dev/docs/api/checkout-ui-extensions/2023-04/apis/checkoutapi' md: >- https://shopify.dev/docs/api/checkout-ui-extensions/2023-04/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 points 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 cart or checkout: * If `type` is `updateMetafield` or `removeMetafield`, 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. Metafields written by `updateMetafield` are carried over to the order. * If `type` is `updateCartMetafield` or `removeCartMetafield`, this mutation updates the metafield attached to the cart and results in an update to the value retrieved through the [`appMetafields`](https://shopify.dev/docs/api/checkout-ui-extensions/2023-04/apis/standardapi#properties-propertydetail-appmetafields) property. Metafields written by `updateCartMetafields` are updated on the cart object only and are **not** carried over to the order. **Tip:** Cart metafields are only available on carts created via the Storefront API version \2023-04\ or later. * **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. ### 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 \`MetafieldRemoveCartChange\` 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 \`MetafieldUpdateCartChange\` 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 ``` Examples ### Examples * #### ##### React ```jsx import { render, Checkbox, useApplyAttributeChange, } from '@shopify/checkout-ui-extensions-react'; // 1. Choose an extension point render('Checkout::Dynamic::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 { extend, Checkbox, } from '@shopify/checkout-ui-extensions'; // 1. Choose an extension point extend( 'Checkout::Dynamic::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 - CartLineDetailsApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cartlinedetailsapi) [APIs - PickupPointsApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuppointsapi) [APIs - PickupLocationsApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuplocationsapi) [APIs - ShippingMethodDetailsApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/shippingmethoddetailsapi) [APIs - ExtensionPoints](https://shopify.dev/docs/api/checkout-ui-extensions/apis/extensionpoints)