---
title: Cart Instructions API
description: Instructions used to create the checkout.
api_version: 2025-07
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/target-apis/checkout-apis/cart-instructions-api
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/target-apis/checkout-apis/cart-instructions-api.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/checkout-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/upgrading-to-2026-04) to upgrade your extension.

# Cart Instructions API

Instructions used to create the checkout.

## StandardApi

The base API object provided to `purchase` extension targets.

* **instructions**

  **StatefulRemoteSubscribable\<CartInstructions>**

  **required**

  The cart instructions used to create the checkout and possibly limit extension capabilities.

  These instructions should be checked prior to performing any actions that may be affected by them.

  For example, if you intend to add a discount code via the `applyDiscountCodeChange` method, check `discounts.canUpdateDiscountCodes` to ensure it's supported in this checkout.

  **Caution:** As of version \<code>2024-07\</code>, UI extension code must check for instructions before calling select APIs in case those APIs are not available. See the \<a href="/docs/api/checkout-ui-extensions/apis/cart-instructions#examples">update guide\</a> for more information.

### CartInstructions

* attributes

  Cart instructions related to cart attributes.

  ```ts
  AttributesCartInstructions
  ```

* delivery

  Cart instructions related to delivery.

  ```ts
  DeliveryCartInstructions
  ```

* discounts

  Cart instructions related to discounts.

  ```ts
  DiscountsCartInstructions
  ```

* lines

  Cart instructions related to cart lines.

  ```ts
  CartLinesCartInstructions
  ```

* metafields

  Cart instructions related to metafields.

  ```ts
  MetafieldsCartInstructions
  ```

* notes

  Cart instructions related to notes.

  ```ts
  NotesCartInstructions
  ```

### AttributesCartInstructions

* canUpdateAttributes

  Indicates whether or not cart attributes can be updated.

  ```ts
  boolean
  ```

### DeliveryCartInstructions

* canSelectCustomAddress

  Indicates whether a buyer can select a custom address. When true, this implies extensions can update the delivery address.

  ```ts
  boolean
  ```

### DiscountsCartInstructions

* canUpdateDiscountCodes

  Indicates whether or not discount codes can be updated.

  ```ts
  boolean
  ```

### CartLinesCartInstructions

* canAddCartLine

  Indicates whether or not new cart lines can be added.

  ```ts
  boolean
  ```

* canRemoveCartLine

  Indicates whether or not cart lines can be removed.

  ```ts
  boolean
  ```

* canUpdateCartLine

  Indicates whether or not cart lines can be updated.

  ```ts
  boolean
  ```

### MetafieldsCartInstructions

* canDeleteCartMetafield

  Indicates whether or not cart metafields can be deleted.

  ```ts
  boolean
  ```

* canSetCartMetafields

  Indicates whether or not cart metafields can be added or updated.

  ```ts
  boolean
  ```

### NotesCartInstructions

* canUpdateNote

  Indicates whether or not notes can be updated.

  ```ts
  boolean
  ```

## use​Instructions()

Returns the cart instructions used to create the checkout and possibly limit extension capabilities.

### Returns

* **CartInstructions**

  ### ### CartInstructions

  * **attributes**

    **AttributesCartInstructions**

    Cart instructions related to cart attributes.

  * **delivery**

    **DeliveryCartInstructions**

    Cart instructions related to delivery.

  * **discounts**

    **DiscountsCartInstructions**

    Cart instructions related to discounts.

  * **lines**

    **CartLinesCartInstructions**

    Cart instructions related to cart lines.

  * **metafields**

    **MetafieldsCartInstructions**

    Cart instructions related to metafields.

  * **notes**

    **NotesCartInstructions**

    Cart instructions related to notes.

Examples

### Examples

* #### Discounts

  ##### Description

  Check \`instructions.discounts.canUpdateDiscountCodes\` before calling \`applyDiscountCodeChange()\`.

  ##### React

  ```jsx
  import {
    Banner,
    Button,
    useApplyDiscountCodeChange,
    useInstructions,
    reactExtension,
  } from '@shopify/ui-extensions-react/checkout';

  export default reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

  function Extension() {
    const applyDiscountCodeChange =
      useApplyDiscountCodeChange();
    const instructions = useInstructions();

    if (
      instructions.discounts.canUpdateDiscountCodes
    ) {
      return (
        <Button
          onPress={() =>
            applyDiscountCodeChange({
              type: 'addDiscountCode',
              code: 'FREE_SHIPPING',
            })
          }
        >
          Apply your loyalty discount
        </Button>
      );
    } else {
      return (
        <Banner status="warning">
          Loyalty discounts are unavailable
        </Banner>
      );
    }
  }
  ```

  ##### JavaScript

  ```js
  import {
    extension,
    Banner,
    Button,
  } from '@shopify/ui-extensions/checkout';

  export default extension(
    'purchase.checkout.block.render',
    (root, api) => {
      if (
        api.instructions.current.discounts
          .canUpdateDiscountCodes
      ) {
        root.appendChild(
          root.createComponent(
            Button,
            {
              onPress: () =>
                api.applyDiscountCodeChange({
                  type: 'addDiscountCode',
                  code: 'FREE_SHIPPING',
                }),
            },
            'Apply your loyalty discount',
          ),
        );
      } else {
        root.appendChild(
          root.createComponent(
            Banner,
            {},
            'Loyalty discounts are unavailable',
          ),
        );
      }
    },
  );
  ```

* #### Attributes

  ##### Description

  Check \`instructions.attributes.canUpdateAttributes\` before calling \`applyAttributeChange()\`.

  ##### React

  ```jsx
  import {
    Banner,
    Button,
    useApplyAttributeChange,
    useInstructions,
    reactExtension,
  } from '@shopify/ui-extensions-react/checkout';

  export default reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

  function Extension() {
    const applyAttributeChange =
      useApplyAttributeChange();
    const instructions = useInstructions();

    if (
      instructions.attributes.canUpdateAttributes
    ) {
      return (
        <Button
          onPress={() =>
            applyAttributeChange({
              type: 'updateAttribute',
              key: 'loyaltyPoints',
              value: '100',
            })
          }
        >
          Apply 100 loyalty points
        </Button>
      );
    } else {
      return (
        <Banner status="warning">
          Loyalty points are unavailable
        </Banner>
      );
    }
  }
  ```

  ##### JavaScript

  ```js
  import {
    extension,
    Banner,
    Button,
  } from '@shopify/ui-extensions/checkout';

  export default extension(
    'purchase.checkout.block.render',
    (root, api) => {
      if (
        api.instructions.current.attributes
          .canUpdateAttributes
      ) {
        root.appendChild(
          root.createComponent(
            Button,
            {
              onPress: () =>
                api.applyAttributeChange({
                  type: 'updateAttribute',
                  key: 'loyaltyPoints',
                  value: '100',
                }),
            },
            'Apply 100 loyalty points',
          ),
        );
      } else {
        root.appendChild(
          root.createComponent(
            Banner,
            {},
            'Loyalty points are unavailable',
          ),
        );
      }
    },
  );
  ```

* #### Delivery

  ##### Description

  Check \`instructions.delivery.canSelectCustomAddress\` before calling \`applyShippingAddressChange()\`. When \`true\`, this instruction implies that extensions can change the shipping address.

  ##### React

  ```jsx
  import {
    Banner,
    Button,
    useApplyShippingAddressChange,
    useInstructions,
    reactExtension,
  } from '@shopify/ui-extensions-react/checkout';

  export default reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

  function Extension() {
    const applyShippingAddressChange =
      useApplyShippingAddressChange();
    const instructions = useInstructions();

    if (
      instructions.delivery.canSelectCustomAddress
    ) {
      return (
        <Button
          onPress={() =>
            applyShippingAddressChange({
              type: 'updateShippingAddress',
              address: {
                zip: '90201',
              },
            })
          }
        >
          Change your postal code
        </Button>
      );
    } else {
      return (
        <Banner status="warning">
          Shipping address cannot be modified
        </Banner>
      );
    }
  }
  ```

  ##### JavaScript

  ```js
  import {
    extension,
    Banner,
    Button,
  } from '@shopify/ui-extensions/checkout';

  export default extension(
    'purchase.checkout.block.render',
    (root, api) => {
      if (
        api.instructions.current.delivery
          .canSelectCustomAddress
      ) {
        root.appendChild(
          root.createComponent(
            Button,
            {
              onPress: () =>
                api.applyShippingAddressChange({
                  type: 'updateShippingAddress',
                  address: {
                    zip: '90201',
                  },
                }),
            },
            'Change your postal code',
          ),
        );
      } else {
        root.appendChild(
          root.createComponent(
            Banner,
            {},
            'Shipping address cannot be modified',
          ),
        );
      }
    },
  );
  ```

* #### Discounts

  ##### Description

  Check \`instructions.discounts.canUpdateDiscountCodes\` before calling \`applyDiscountCodeChange()\`.

  ##### React

  ```jsx
  import {
    Banner,
    Button,
    useApplyDiscountCodeChange,
    useInstructions,
    reactExtension,
  } from '@shopify/ui-extensions-react/checkout';

  export default reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

  function Extension() {
    const applyDiscountCodeChange =
      useApplyDiscountCodeChange();
    const instructions = useInstructions();

    if (
      instructions.discounts.canUpdateDiscountCodes
    ) {
      return (
        <Button
          onPress={() =>
            applyDiscountCodeChange({
              type: 'addDiscountCode',
              code: 'FREE_SHIPPING',
            })
          }
        >
          Apply your loyalty discount
        </Button>
      );
    } else {
      return (
        <Banner status="warning">
          Loyalty discounts are unavailable
        </Banner>
      );
    }
  }
  ```

  ##### JavaScript

  ```js
  import {
    extension,
    Banner,
    Button,
  } from '@shopify/ui-extensions/checkout';

  export default extension(
    'purchase.checkout.block.render',
    (root, api) => {
      if (
        api.instructions.current.discounts
          .canUpdateDiscountCodes
      ) {
        root.appendChild(
          root.createComponent(
            Button,
            {
              onPress: () =>
                api.applyDiscountCodeChange({
                  type: 'addDiscountCode',
                  code: 'FREE_SHIPPING',
                }),
            },
            'Apply your loyalty discount',
          ),
        );
      } else {
        root.appendChild(
          root.createComponent(
            Banner,
            {},
            'Loyalty discounts are unavailable',
          ),
        );
      }
    },
  );
  ```

* #### Lines

  ##### Description

  Check \`instructions.lines.canAddCartLine\` or \`instructions.lines.canRemoveCartLine\` or \`instructions.lines.canUpdateCartLine\` before calling \`applyCartLinesChange()\`.

  ##### React

  ```jsx
  import {
    Banner,
    Button,
    useApplyCartLinesChange,
    useInstructions,
    reactExtension,
  } from '@shopify/ui-extensions-react/checkout';

  export default reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

  function Extension() {
    const applyCartLinesChange =
      useApplyCartLinesChange();
    const instructions = useInstructions();

    if (instructions.lines.canAddCartLine) {
      return (
        <Button
          onPress={() =>
            applyCartLinesChange({
              type: 'addCartLine',
              merchandiseId:
                'gid://shopify/product/1234',
              quantity: 1,
            })
          }
        >
          Add a free gift to your order
        </Button>
      );
    } else {
      return (
        <Banner status="warning">
          The products in your cart cannot be
          modified
        </Banner>
      );
    }
  }
  ```

  ##### JavaScript

  ```js
  import {
    extension,
    Banner,
    Button,
  } from '@shopify/ui-extensions/checkout';

  export default extension(
    'purchase.checkout.block.render',
    (root, api) => {
      if (
        api.instructions.current.lines
          .canAddCartLine
      ) {
        root.appendChild(
          root.createComponent(
            Button,
            {
              onPress: () =>
                api.applyCartLinesChange({
                  type: 'addCartLine',
                  merchandiseId:
                    'gid://shopify/product/1234',
                  quantity: 1,
                }),
            },
            'Add a free gift to your order',
          ),
        );
      } else {
        root.appendChild(
          root.createComponent(
            Banner,
            {},
            'The products in your cart cannot be modified',
          ),
        );
      }
    },
  );
  ```

* #### Metafields

  ##### Description

  Check \`instructions.metafields.canSetCartMetafields\` or \`instructions.metafields.canDeleteCartMetafields\` before calling \`applyMetafieldChange()\` if you are working with cart metafields.

  ##### React

  ```jsx
  import {
    Banner,
    Button,
    useApplyMetafieldChange,
    useInstructions,
    reactExtension,
  } from '@shopify/ui-extensions-react/checkout';

  export default reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

  function Extension() {
    const applyMetafieldChange =
      useApplyMetafieldChange();
    const instructions = useInstructions();

    if (
      instructions.metafields.canSetCartMetafields
    ) {
      return (
        <Button
          onPress={() =>
            applyMetafieldChange({
              type: 'updateCartMetafield',
              metafield: {
                namespace: 'loyalty',
                key: 'loyaltyPoints',
                value: '100',
                type: 'string',
              },
            })
          }
        >
          Apply 100 loyalty points
        </Button>
      );
    } else {
      return (
        <Banner status="warning">
          Loyalty points are unavailable
        </Banner>
      );
    }
  }
  ```

  ##### JavaScript

  ```js
  import {
    extension,
    Banner,
    Button,
  } from '@shopify/ui-extensions/checkout';

  export default extension(
    'purchase.checkout.block.render',
    (root, api) => {
      if (
        api.instructions.current.metafields
          .canSetCartMetafields
      ) {
        root.appendChild(
          root.createComponent(
            Button,
            {
              onPress: () =>
                api.applyMetafieldChange({
                  type: 'updateCartMetafield',
                  metafield: {
                    namespace: 'loyalty',
                    key: 'loyaltyPoints',
                    value: '100',
                    type: 'string',
                  },
                }),
            },
            'Apply 100 loyalty points',
          ),
        );
      } else {
        root.appendChild(
          root.createComponent(
            Banner,
            {},
            'Loyalty points are unavailable',
          ),
        );
      }
    },
  );
  ```

* #### Notes

  ##### Description

  Check \`instructions.notes.canUpdateNote\` before calling \`applyNoteChange()\`.

  ##### React

  ```jsx
  import {
    Banner,
    Button,
    useApplyNoteChange,
    useInstructions,
    reactExtension,
  } from '@shopify/ui-extensions-react/checkout';

  export default reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

  function Extension() {
    const applyNoteChange = useApplyNoteChange();
    const instructions = useInstructions();

    if (instructions.notes.canUpdateNote) {
      return (
        <Button
          onPress={() =>
            applyNoteChange({
              type: 'updateNote',
              note: 'Please include a free gift.',
            })
          }
        >
          Include a free gift with your order
        </Button>
      );
    } else {
      return (
        <Banner status="warning">
          Free gifts cannot be added to this order
        </Banner>
      );
    }
  }
  ```

  ##### JavaScript

  ```js
  import {
    extension,
    Banner,
    Button,
  } from '@shopify/ui-extensions/checkout';

  export default extension(
    'purchase.checkout.block.render',
    (root, api) => {
      if (
        api.instructions.current.notes.canUpdateNote
      ) {
        root.appendChild(
          root.createComponent(
            Button,
            {
              onPress: () =>
                api.applyNoteChange({
                  type: 'updateNote',
                  note: 'Please include a free gift.',
                }),
            },
            'Include a free gift with your order',
          ),
        );
      } else {
        root.appendChild(
          root.createComponent(
            Banner,
            {},
            'Free gifts cannot be added to this order',
          ),
        );
      }
    },
  );
  ```

## Related

[Reference - Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)

[Reference - Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)

[Reference - Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)

[Learn - Tutorials](https://shopify.dev/apps/checkout)