---
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](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 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\<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 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\<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.

### 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 \`MetafieldRemoveCartChange\` 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 `MetafieldRemoveCartChange` 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 \`MetafieldUpdateCartChange\` API.

  ```ts
  "updateCartMetafield"
  ```

* metafield

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

```ts
export interface MetafieldUpdateCartChange {
  /**
   * The type of the `MetafieldUpdateCartChange` 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;
}
```

### Examples

* ####

  ##### React

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

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