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

# Cart Instructions API

Instructions used to create the checkout.

### Support Targets (31)

### Supported targets

* purchase.​checkout.​actions.​render-before
* purchase.​checkout.​block.​render
* purchase.​checkout.​cart-line-item.​render-after
* purchase.​checkout.​cart-line-list.​render-after
* purchase.​checkout.​chat.​render
* purchase.​checkout.​contact.​render-after
* purchase.​checkout.​delivery-address.​render-after
* purchase.​checkout.​delivery-address.​render-before
* purchase.​checkout.​footer.​render-after
* purchase.​checkout.​header.​render-after
* purchase.​checkout.​payment-method-list.​render-after
* purchase.​checkout.​payment-method-list.​render-before
* purchase.​checkout.​pickup-location-list.​render-after
* purchase.​checkout.​pickup-location-list.​render-before
* purchase.​checkout.​pickup-location-option-item.​render-after
* purchase.​checkout.​pickup-point-list.​render-after
* purchase.​checkout.​pickup-point-list.​render-before
* purchase.​checkout.​reductions.​render-after
* purchase.​checkout.​reductions.​render-before
* purchase.​checkout.​shipping-option-item.​details.​render
* purchase.​checkout.​shipping-option-item.​render-after
* purchase.​checkout.​shipping-option-list.​render-after
* purchase.​checkout.​shipping-option-list.​render-before
* purchase.​thank-you.​announcement.​render
* purchase.​thank-you.​block.​render
* purchase.​thank-you.​cart-line-item.​render-after
* purchase.​thank-you.​cart-line-list.​render-after
* purchase.​thank-you.​chat.​render
* purchase.​thank-you.​customer-information.​render-after
* purchase.​thank-you.​footer.​render-after
* purchase.​thank-you.​header.​render-after

## StandardApi

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

* **instructions**

  **SubscribableSignalLike\<CartInstructions>**

  **required**

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

  These instructions should be checked before performing any actions that might 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 aren\&#39;t available. See the \<a href="/docs/api/checkout-ui-extensions/2026-04/apis/cart-instructions#examples">update guide\</a> for more information.

### SubscribableSignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends \`ReadonlySignalLike\` with deprecated fields that are still supported for backwards compatibility.

* current

  The current value of the signal. Equivalent to \`.value\`, accessing this property subscribes to changes when used in a reactive context.

  ```ts
  T
  ```

* destroy

  Cleans up the subscription and releases any resources held by this signal. After calling \`destroy()\`, the signal stops receiving updates from the main thread.

  ```ts
  () => Promise<void>
  ```

* subscribe

  Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.

  ```ts
  (fn: (value: T) => void) => () => void
  ```

* value

  The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.

  ```ts
  T
  ```

### CartInstructions

* attributes

  Whether the extension can update custom attributes using \`applyAttributeChange()\`.

  ```ts
  AttributesCartInstructions
  ```

* delivery

  Whether the extension can modify the shipping address using \`applyShippingAddressChange()\`.

  ```ts
  DeliveryCartInstructions
  ```

* discounts

  Whether the extension can add or remove discount codes using \`applyDiscountCodeChange()\`.

  ```ts
  DiscountsCartInstructions
  ```

* lines

  Whether the extension can add, remove, or update cart lines using \`applyCartLinesChange()\`.

  ```ts
  CartLinesCartInstructions
  ```

* metafields

  Whether the extension can add, update, or delete cart metafields using \`applyMetafieldChange()\`.

  ```ts
  MetafieldsCartInstructions
  ```

* notes

  Whether the extension can update the order note using \`applyNoteChange()\`.

  ```ts
  NotesCartInstructions
  ```

### AttributesCartInstructions

* canUpdateAttributes

  Whether attributes can be updated using \`applyAttributeChange()\`. When \`false\`, the checkout configuration doesn't allow attribute changes. Even when \`true\`, calls to \`applyAttributeChange()\` can still fail during accelerated checkout (Apple Pay, Google Pay).

  ```ts
  boolean
  ```

### DeliveryCartInstructions

* canSelectCustomAddress

  Whether the shipping address can be modified using \`applyShippingAddressChange()\`. When \`false\`, the buyer is using an accelerated checkout flow (Apple Pay, Google Pay) where the address can't be changed.

  ```ts
  boolean
  ```

### DiscountsCartInstructions

* canUpdateDiscountCodes

  Whether discount codes can be updated using \`applyDiscountCodeChange()\`. When \`false\`, the checkout configuration doesn't allow discount code changes. Even when \`true\`, calls to \`applyDiscountCodeChange()\` can still fail during accelerated checkout (Apple Pay, Google Pay).

  ```ts
  boolean
  ```

### CartLinesCartInstructions

* canAddCartLine

  Whether new cart lines can be added using \`applyCartLinesChange()\`. When \`false\`, the checkout configuration doesn't allow adding lines (for example, draft orders). Even when \`true\`, calls can still fail during accelerated checkout (Apple Pay, Google Pay).

  ```ts
  boolean
  ```

* canRemoveCartLine

  Whether cart lines can be removed using \`applyCartLinesChange()\`. When \`false\`, the checkout configuration doesn't allow removing lines. Even when \`true\`, calls can still fail during accelerated checkout.

  ```ts
  boolean
  ```

* canUpdateCartLine

  Whether cart lines can be updated using \`applyCartLinesChange()\`. When \`false\`, the checkout configuration doesn't allow updating lines. Even when \`true\`, calls can still fail during accelerated checkout.

  ```ts
  boolean
  ```

### MetafieldsCartInstructions

* canDeleteCartMetafield

  Whether the extension can delete cart metafields using \`applyMetafieldChange()\`.

  ```ts
  boolean
  ```

* canSetCartMetafields

  Whether the extension can add or update cart metafields using \`applyMetafieldChange()\`.

  ```ts
  boolean
  ```

### NotesCartInstructions

* canUpdateNote

  Whether the order note can be updated using \`applyNoteChange()\`. When \`false\`, the checkout configuration doesn't allow note changes. Even when \`true\`, calls to \`applyNoteChange()\` can still fail during accelerated checkout (Apple Pay, Google Pay).

  ```ts
  boolean
  ```

## use​Instructions()

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

### Returns

* **CartInstructions**

  ### ### CartInstructions

  * **attributes**

    **AttributesCartInstructions**

    Whether the extension can update custom attributes using `applyAttributeChange()`.

  * **delivery**

    **DeliveryCartInstructions**

    Whether the extension can modify the shipping address using `applyShippingAddressChange()`.

  * **discounts**

    **DiscountsCartInstructions**

    Whether the extension can add or remove discount codes using `applyDiscountCodeChange()`.

  * **lines**

    **CartLinesCartInstructions**

    Whether the extension can add, remove, or update cart lines using `applyCartLinesChange()`.

  * **metafields**

    **MetafieldsCartInstructions**

    Whether the extension can add, update, or delete cart metafields using `applyMetafieldChange()`.

  * **notes**

    **NotesCartInstructions**

    Whether the extension can update the order note using `applyNoteChange()`.

Examples

### Examples

* #### Discounts

  ##### Description

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

  ##### Preact

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default function extension() {
    render(<Extension />, document.body);
  }

  function Extension() {
    if (
      shopify.instructions.value.discounts
        .canUpdateDiscountCodes
    ) {
      return (
        <s-button
          onClick={() =>
            shopify.applyDiscountCodeChange({
              type: 'addDiscountCode',
              code: 'FREE_SHIPPING',
            })
          }
        >
          Apply your loyalty discount
        </s-button>
      );
    } else {
      return (
        <s-banner tone="warning">
          Loyalty discounts are unavailable
        </s-banner>
      );
    }
  }
  ```

* #### Attributes

  ##### Description

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

  ##### Preact

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default function extension() {
    render(<Extension />, document.body);
  }

  function Extension() {
    if (
      shopify.instructions.value.attributes
        .canUpdateAttributes
    ) {
      return (
        <s-button
          onClick={() =>
            shopify.applyAttributeChange({
              type: 'updateAttribute',
              key: 'loyaltyPoints',
              value: '100',
            })
          }
        >
          Apply 100 loyalty points
        </s-button>
      );
    } else {
      return (
        <s-banner tone="warning">
          Loyalty points are unavailable
        </s-banner>
      );
    }
  }
  ```

* #### Delivery

  ##### Description

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

  ##### Preact

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default function extension() {
    render(<Extension />, document.body);
  }

  function Extension() {
    if (
      shopify.instructions.value.delivery
        .canSelectCustomAddress
    ) {
      return (
        <s-button
          onClick={() =>
            shopify.applyShippingAddressChange({
              type: 'updateShippingAddress',
              address: {
                zip: '90201',
              },
            })
          }
        >
          Change your postal code
        </s-button>
      );
    } else {
      return (
        <s-banner tone="warning">
          Shipping address cannot be modified
        </s-banner>
      );
    }
  }
  ```

* #### Discounts

  ##### Description

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

  ##### Preact

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default function extension() {
    render(<Extension />, document.body);
  }

  function Extension() {
    if (
      shopify.instructions.value.discounts
        .canUpdateDiscountCodes
    ) {
      return (
        <s-button
          onClick={() =>
            shopify.applyDiscountCodeChange({
              type: 'addDiscountCode',
              code: 'FREE_SHIPPING',
            })
          }
        >
          Apply your loyalty discount
        </s-button>
      );
    } else {
      return (
        <s-banner tone="warning">
          Loyalty discounts are unavailable
        </s-banner>
      );
    }
  }
  ```

* #### Lines

  ##### Description

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

  ##### Preact

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default function extension() {
    render(<Extension />, document.body);
  }

  function Extension() {
    if (
      shopify.instructions.value.lines
        .canAddCartLine
    ) {
      return (
        <s-button
          onClick={() =>
            shopify.applyCartLinesChange({
              type: 'addCartLine',
              merchandiseId:
                'gid://shopify/product/1234',
              quantity: 1,
            })
          }
        >
          Add a free gift to your order
        </s-button>
      );
    } else {
      return (
        <s-banner tone="warning">
          The products in your cart cannot be
          modified
        </s-banner>
      );
    }
  }
  ```

* #### Metafields

  ##### Description

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

  ##### Preact

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default function extension() {
    render(<Extension />, document.body);
  }

  function Extension() {
    if (
      shopify.instructions.value.metafields
        .canSetCartMetafields
    ) {
      return (
        <s-button
          onClick={() =>
            shopify.applyMetafieldChange({
              type: 'updateCartMetafield',
              metafield: {
                namespace: 'loyalty',
                key: 'loyaltyPoints',
                value: '100',
                type: 'string',
              },
            })
          }
        >
          Apply 100 loyalty points
        </s-button>
      );
    } else {
      return (
        <s-banner tone="warning">
          Loyalty points are unavailable
        </s-banner>
      );
    }
  }
  ```

* #### Notes

  ##### Description

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

  ##### Preact

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default function extension() {
    render(<Extension />, document.body);
  }

  function Extension() {
    if (
      shopify.instructions.value.notes.canUpdateNote
    ) {
      return (
        <s-button
          onClick={() =>
            shopify.applyNoteChange({
              type: 'updateNote',
              note: 'Please include a free gift.',
            })
          }
        >
          Include a free gift with your order
        </s-button>
      );
    } else {
      return (
        <s-banner tone="warning">
          Free gifts cannot be added to this order
        </s-banner>
      );
    }
  }
  ```

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