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

# Cart InstructionsAPI

Instructions used to create the checkout.

## 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 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 `2024-07`, UI extension code must check for instructions before calling select APIs in case those APIs are not available. See the [update guide](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cart-instructions#examples) for more information.

### SubscribableSignalLike

Represents a read-only value managed on the main thread that an extension can subscribe to. Example: Checkout uses this to manage the state of an object and communicate state changes to extensions running in a sandboxed web worker. This interface is compatible with \[Preact's ReadonlySignal]\(https\://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709). Some fields are deprecated but still supported for backwards compatibility. In version 2025-10, \[\`StatefulRemoteSubscribable\`]\(https\://github.com/Shopify/remote-dom/blob/03929aa8418a89d41d294005f219837582718df8/packages/async-subscription/src/types.ts#L17) was replaced with \`ReadonlySignalLike\`. Checkout will remove the old fields some time in the future.

* current

  ```ts
  T
  ```

* destroy

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

* subscribe

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

* value

  ```ts
  T
  ```

```ts
export interface SubscribableSignalLike<T> extends ReadonlySignalLike<T> {
  /**
   * @deprecated Use `.value` instead.
   */
  readonly current: T;
  /**
   * @deprecated No longer needed. Use Preact Signal management instead.
   */
  destroy(): Promise<void>;
}
```

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

```ts
export interface CartInstructions {
  /**
   * Cart instructions related to cart attributes.
   */
  attributes: AttributesCartInstructions;

  /**
   * Cart instructions related to delivery.
   */
  delivery: DeliveryCartInstructions;

  /**
   * Cart instructions related to discounts.
   */
  discounts: DiscountsCartInstructions;

  /**
   * Cart instructions related to cart lines.
   */
  lines: CartLinesCartInstructions;

  /**
   * Cart instructions related to metafields.
   */
  metafields: MetafieldsCartInstructions;

  /**
   * Cart instructions related to notes.
   */
  notes: NotesCartInstructions;
}
```

### AttributesCartInstructions

* canUpdateAttributes

  Indicates whether or not cart attributes can be updated.

  ```ts
  boolean
  ```

```ts
export interface AttributesCartInstructions {
  /**
   * Indicates whether or not cart attributes can be updated.
   */
  canUpdateAttributes: boolean;
}
```

### DeliveryCartInstructions

* canSelectCustomAddress

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

  ```ts
  boolean
  ```

```ts
export interface DeliveryCartInstructions {
  /**
   * Indicates whether a buyer can select a custom address.
   *
   * When true, this implies extensions can update the delivery address.
   */
  canSelectCustomAddress: boolean;
}
```

### DiscountsCartInstructions

* canUpdateDiscountCodes

  Indicates whether or not discount codes can be updated.

  ```ts
  boolean
  ```

```ts
export interface DiscountsCartInstructions {
  /**
   * Indicates whether or not discount codes can be updated.
   */
  canUpdateDiscountCodes: 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
  ```

```ts
export interface CartLinesCartInstructions {
  /**
   * Indicates whether or not new cart lines can be added.
   */
  canAddCartLine: boolean;

  /**
   * Indicates whether or not cart lines can be removed.
   */
  canRemoveCartLine: boolean;

  /**
   * Indicates whether or not cart lines can be updated.
   */
  canUpdateCartLine: 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
  ```

```ts
export interface MetafieldsCartInstructions {
  /**
   * Indicates whether or not cart metafields can be added or updated.
   */
  canSetCartMetafields: boolean;

  /**
   * Indicates whether or not cart metafields can be deleted.
   */
  canDeleteCartMetafield: boolean;
}
```

### NotesCartInstructions

* canUpdateNote

  Indicates whether or not notes can be updated.

  ```ts
  boolean
  ```

```ts
export interface NotesCartInstructions {
  /**
   * Indicates whether or not notes can be updated.
   */
  canUpdateNote: 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.

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

```ts
export interface CartInstructions {
  /**
   * Cart instructions related to cart attributes.
   */
  attributes: AttributesCartInstructions;

  /**
   * Cart instructions related to delivery.
   */
  delivery: DeliveryCartInstructions;

  /**
   * Cart instructions related to discounts.
   */
  discounts: DiscountsCartInstructions;

  /**
   * Cart instructions related to cart lines.
   */
  lines: CartLinesCartInstructions;

  /**
   * Cart instructions related to metafields.
   */
  metafields: MetafieldsCartInstructions;

  /**
   * Cart instructions related to notes.
   */
  notes: NotesCartInstructions;
}
```

### AttributesCartInstructions

* canUpdateAttributes

  Indicates whether or not cart attributes can be updated.

  ```ts
  boolean
  ```

```ts
export interface AttributesCartInstructions {
  /**
   * Indicates whether or not cart attributes can be updated.
   */
  canUpdateAttributes: boolean;
}
```

### DeliveryCartInstructions

* canSelectCustomAddress

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

  ```ts
  boolean
  ```

```ts
export interface DeliveryCartInstructions {
  /**
   * Indicates whether a buyer can select a custom address.
   *
   * When true, this implies extensions can update the delivery address.
   */
  canSelectCustomAddress: boolean;
}
```

### DiscountsCartInstructions

* canUpdateDiscountCodes

  Indicates whether or not discount codes can be updated.

  ```ts
  boolean
  ```

```ts
export interface DiscountsCartInstructions {
  /**
   * Indicates whether or not discount codes can be updated.
   */
  canUpdateDiscountCodes: 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
  ```

```ts
export interface CartLinesCartInstructions {
  /**
   * Indicates whether or not new cart lines can be added.
   */
  canAddCartLine: boolean;

  /**
   * Indicates whether or not cart lines can be removed.
   */
  canRemoveCartLine: boolean;

  /**
   * Indicates whether or not cart lines can be updated.
   */
  canUpdateCartLine: 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
  ```

```ts
export interface MetafieldsCartInstructions {
  /**
   * Indicates whether or not cart metafields can be added or updated.
   */
  canSetCartMetafields: boolean;

  /**
   * Indicates whether or not cart metafields can be deleted.
   */
  canDeleteCartMetafield: boolean;
}
```

### NotesCartInstructions

* canUpdateNote

  Indicates whether or not notes can be updated.

  ```ts
  boolean
  ```

```ts
export interface NotesCartInstructions {
  /**
   * Indicates whether or not notes can be updated.
   */
  canUpdateNote: boolean;
}
```

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

## Examples

Use the cart instructions API to determine if the affected APIs are available in checkout.

Attributes

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

Delivery

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

Discounts

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

Lines

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

Metafields

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

Notes

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

### Examples

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

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/targets)

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

[![](https://shopify.dev/images/icons/32/apps.png)![](https://shopify.dev/images/icons/32/apps-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/components)

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

[![](https://shopify.dev/images/icons/32/gear.png)![](https://shopify.dev/images/icons/32/gear-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)

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

[![](https://shopify.dev/images/icons/32/tutorial.png)![](https://shopify.dev/images/icons/32/tutorial-dark.png)](https://shopify.dev/apps/checkout)

[LearnTutorials](https://shopify.dev/apps/checkout)