# CheckoutApi

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.

### 

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

// 1. Choose an extension point
render('Checkout::Dynamic::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 {
  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,
      );
    }
  },
);

```


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

### applyAttributeChange
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`](/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
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`](/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
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`](/docs/api/checkout-ui-extensions/apis/standardapi#properties-propertydetail-discountcodes) property.

> Caution:
> See [security considerations](/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
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`](/docs/api/checkout-ui-extensions/apis/standardapi#properties-propertydetail-appliedgiftcards) property.

> Caution:
> See [security considerations](/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
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`](/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`](/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
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`](/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.
### key
Key of the attribute to add or update
### value
Value for the attribute to add or update
### Attribute

### key
The key for the attribute.
### value
The value for the attribute.
### AttributeChangeResult

AttributeChangeResultSuccess | AttributeChangeResultError
### AttributeChangeResultSuccess
The returned result of a successful update to an attribute.
### type
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
The type of the `AttributeChangeResultError` API.
### 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.
### CartLineChange

CartLineAddChange | CartLineRemoveChange | CartLineUpdateChange
### CartLineAddChange

### type
An identifier for changes that add line items.
### merchandiseId
The merchandise ID being added.
### quantity
The quantity of the merchandise being added.
### attributes
The attributes associated with the line item.
### sellingPlanId
The identifier of the selling plan that the merchandise is being purchased
with.
### CartLine

### id
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
The merchandise being purchased.
### quantity
The quantity of the merchandise being purchased.
### cost
The details about the cost components attributed to the cart line.
### attributes
The line item additional custom attributes.
### discountAllocations
Discounts applied to the cart line.
### lineComponents
Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.
### Merchandise

### type

### id
A globally-unique identifier.
### title
The product variant’s title.
### subtitle
The product variant's subtitle.
### image
Image associated with the product variant. This field falls back to the product
image if no image is available.
### selectedOptions
List of product options applied to the variant.
### product
The product object that the product variant belongs to.
### requiresShipping
Whether or not the product requires shipping.
### sellingPlan
The selling plan associated with the merchandise.
### ImageDetails

### url
The image URL.
### altText
The alternative text for the image.
### SelectedOption

### name
The name of the merchandise option.
### value
The value of the merchandise option.
### Product

### id
A globally-unique identifier.
### vendor
The product’s vendor name.
### productType
A categorization that a product can be tagged with, commonly used for filtering and searching.
### SellingPlan

### id
A globally-unique identifier.
### CartLineCost

### totalAmount
The total amount after reductions the buyer can expect to pay that is directly attributable to a single
cart line.
### Money

### amount
The price amount.
### currencyCode
The ISO 4217 format for the currency.
### 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'
### CartDiscountAllocation

CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation
### CartCodeDiscountAllocation

### code
The code for the discount
### type
The type of the code discount
### discountedAmount
The money amount that has been discounted from the order
### CartAutomaticDiscountAllocation

### title
The title of the automatic discount
### type
The type of the automatic discount
### discountedAmount
The money amount that has been discounted from the order
### CartCustomDiscountAllocation

### title
The title of the custom discount
### type
The type of the custom discount
### discountedAmount
The money amount that has been discounted from the order
### CartBundleLineComponent

### type

### id
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
The merchandise of this bundle line component.
### quantity
The quantity of merchandise being purchased.
### cost
The cost attributed to this bundle line component.
### attributes
Additional custom attributes for the bundle line component.
### CartLineRemoveChange

### type
An identifier for changes that remove line items.
### id
Line Item ID.
### quantity
The quantity being removed for this line item.
### CartLineUpdateChange

### type
An identifier for changes that update line items.
### id
Line Item ID.
### merchandiseId
The new merchandise ID for the line item.
### quantity
The new quantity for the line item.
### attributes
The new attributes for the line item.
### 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.
### CartLineChangeResult

CartLineChangeResultSuccess | CartLineChangeResultError
### CartLineChangeResultSuccess

### type
Indicates that the line item was changed successfully.
### CartLineChangeResultError

### type
Indicates that the line item was not changed successfully. Refer to the `message` property for details about the 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.
### DiscountCodeChange

DiscountCodeAddChange | DiscountCodeRemoveChange
### DiscountCodeAddChange

### type
The type of the `DiscountCodeChange` API.
### code
The code for the discount
### DiscountCodeRemoveChange

### type
The type of the `DiscountCodeChange` API.
### code
The code for the discount
### DiscountCodeChangeResult

DiscountCodeChangeResultSuccess | DiscountCodeChangeResultError
### DiscountCodeChangeResultSuccess

### type
Indicates that the discount code change was applied successfully.
### DiscountCodeChangeResultError

### type
Indicates that the discount code change failed.
### 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.
### GiftCardChange

GiftCardAddChange | GiftCardRemoveChange
### GiftCardAddChange

### type
The type of the `GiftCardChange` API.
### code
Gift card code.
### GiftCardRemoveChange

### type
The type of the `GiftCardChange` API.
### code
Gift card code.
### GiftCardChangeResult

GiftCardChangeResultSuccess | GiftCardChangeResultError
### GiftCardChangeResultSuccess

### type
Indicates that the gift card change was applied successfully.
### GiftCardChangeResultError

### type
Indicates that the gift card change failed.
### 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.
### MetafieldChange

MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange
### MetafieldRemoveChange
Removes a metafield.
### type
The type of the `MetafieldRemoveChange` API.
### key
The name of the metafield to remove.
### namespace
The namespace of the metafield to remove.
### Metafield
Metadata associated with the checkout.
### key
The name of the metafield. It must be between 3 and 30 characters in
length (inclusive).
### namespace
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
The information to be stored as metadata.
### valueType
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
The type of the `MetafieldUpdateChange` API.
### key
The name of the metafield to update.
### namespace
The namespace of the metafield to add.
### value
The new information to store in the metafield.
### valueType
The metafield’s information type.
### MetafieldRemoveCartChange
Removes a cart metafield.
### type
The type of the `MetafieldRemoveCartChange` API.
### key
The name of the metafield to remove.
### namespace
The namespace of the metafield to remove.
### 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.
### metafield

### MetafieldChangeResult

MetafieldChangeResultSuccess | MetafieldChangeResultError
### MetafieldChangeResultSuccess

### type
The type of the `MetafieldChangeResultSuccess` API.
### MetafieldChangeResultError

### type
The type of the `MetafieldChangeResultError` API.
### 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.
### NoteChange

NoteRemoveChange | NoteUpdateChange
### NoteRemoveChange
Removes a note
### type
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
The type of the `NoteUpdateChange` API.
### note
The new value of the note.
### NoteChangeResult

NoteChangeResultSuccess | NoteChangeResultError
### NoteChangeResultSuccess

### type
The type of the `NoteChangeResultSuccess` API.
### NoteChangeResultError

### type
The type of the `NoteChangeResultError` API.
### 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.
## Related
- [StandardApi](/docs/api/checkout-ui-extensions/apis/standardapi)
- [OrderStatusApi](/docs/api/checkout-ui-extensions/apis/orderstatusapi)
- [CartLineDetailsApi](/docs/api/checkout-ui-extensions/apis/cartlinedetailsapi)
- [PickupPointsApi](/docs/api/checkout-ui-extensions/apis/pickuppointsapi)
- [PickupLocationsApi](/docs/api/checkout-ui-extensions/apis/pickuplocationsapi)
- [ShippingMethodDetailsApi](/docs/api/checkout-ui-extensions/apis/shippingmethoddetailsapi)
- [ExtensionPoints](/docs/api/checkout-ui-extensions/apis/extensionpoints)