Choose a version:

Cart Instructions

Instructions used to create the checkout.

Anchor to standardapiStandardApi

The base API object provided to purchase extension targets.

Anchor to instructions instructions <> 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 for more information.
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.

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
```
T
```
destroy
```
() => 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.
```
(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.
```
T
```

CartInstructions

attributes
Cart instructions related to cart attributes.
```
AttributesCartInstructions
```
delivery
Cart instructions related to delivery.
```
DeliveryCartInstructions
```
discounts
Cart instructions related to discounts.
```
DiscountsCartInstructions
```
lines
Cart instructions related to cart lines.
```
CartLinesCartInstructions
```
metafields
Cart instructions related to metafields.
```
MetafieldsCartInstructions
```
notes
Cart instructions related to notes.
```
NotesCartInstructions
```

AttributesCartInstructions

canUpdateAttributes
Indicates whether or not cart attributes can be updated.
```
boolean
```

DeliveryCartInstructions

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

DiscountsCartInstructions

canUpdateDiscountCodes
Indicates whether or not discount codes can be updated.
```
boolean
```

CartLinesCartInstructions

canAddCartLine
Indicates whether or not new cart lines can be added.
```
boolean
```
canRemoveCartLine
Indicates whether or not cart lines can be removed.
```
boolean
```
canUpdateCartLine
Indicates whether or not cart lines can be updated.
```
boolean
```

MetafieldsCartInstructions

canDeleteCartMetafield
Indicates whether or not cart metafields can be deleted.
```
boolean
```
canSetCartMetafields
Indicates whether or not cart metafields can be added or updated.
```
boolean
```

NotesCartInstructions

canUpdateNote
Indicates whether or not notes can be updated.
```
boolean
```

Anchor to useInstructions
useInstructions()

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

Anchor to useInstructions-returnsReturns

CartInstructions

attributes: Cart instructions related to cart attributes.
delivery: Cart instructions related to delivery.
discounts: Cart instructions related to discounts.
lines: Cart instructions related to cart lines.
metafields: Cart instructions related to metafields.
notes: Cart instructions related to notes.

CartInstructions

attributes
Cart instructions related to cart attributes.
```
AttributesCartInstructions
```
delivery
Cart instructions related to delivery.
```
DeliveryCartInstructions
```
discounts
Cart instructions related to discounts.
```
DiscountsCartInstructions
```
lines
Cart instructions related to cart lines.
```
CartLinesCartInstructions
```
metafields
Cart instructions related to metafields.
```
MetafieldsCartInstructions
```
notes
Cart instructions related to notes.
```
NotesCartInstructions
```

AttributesCartInstructions

canUpdateAttributes
Indicates whether or not cart attributes can be updated.
```
boolean
```

DeliveryCartInstructions

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

DiscountsCartInstructions

canUpdateDiscountCodes
Indicates whether or not discount codes can be updated.
```
boolean
```

CartLinesCartInstructions

canAddCartLine
Indicates whether or not new cart lines can be added.
```
boolean
```
canRemoveCartLine
Indicates whether or not cart lines can be removed.
```
boolean
```
canUpdateCartLine
Indicates whether or not cart lines can be updated.
```
boolean
```

MetafieldsCartInstructions

canDeleteCartMetafield
Indicates whether or not cart metafields can be deleted.
```
boolean
```
canSetCartMetafields
Indicates whether or not cart metafields can be added or updated.
```
boolean
```

NotesCartInstructions

canUpdateNote
Indicates whether or not notes can be updated.
```
boolean
```

Examples

Preact

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

Discounts

Description

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

Preact

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

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

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

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

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

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

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