Updating to 2025-01

Some checkouts may be created with cart instructions that prevent buyers from making certain changes to their checkout.

As of version 2024-07, UI extensions must check for instructions before calling select APIs, to properly handle checkouts where those APIs are not available.

Caution

As of July 22nd, 2024, all UI extensions on this version will render in draft order invoice checkouts. As draft order invoice checkouts have restrictions on what buyers can edit, UI extensions in draft order invoice checkouts will be subject to cart instructions.

Choose a version:

Anchor to instruction-checkingRequired instruction checking

You will need to check for cart instructions before calling the following APIs:

Extension API	As of January 2025
applyAttributeChange()	Attributes cannot be modified on draft order checkouts.
applyShippingAddressChange()	Buyers cannot change the address on a draft order checkout if it has fixed shipping rates.
applyDiscountCodeChange()	By default, discounts cannot be modified in draft order checkouts. Merchants must allow it via a setting on the draft order.
applyCartLinesChange()	Cart lines cannot be modified on draft order checkouts.
applyMetafieldChange()	Cart metafields cannot be modified on draft order checkouts. Metafields can still be modified.
applyNoteChange()	Notes cannot be modified on draft order checkouts.

Caution

If you don't check for instructions, the APIs will return an error when they're not available in a given checkout

Learn moreCart Instructions API

Anchor to migrating-apisChecking for cart instructions

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

Anchor to checking-for-cart-instructions-changes-to-applyattributechange()Changes to applyAttributeChange()

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

Anchor to checking-for-cart-instructions-changes-to-applyshippingaddresschange()Changes to applyShippingAddressChange()

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

Anchor to checking-for-cart-instructions-changes-to-applydiscountcodechange()Changes to applyDiscountCodeChange()

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

Anchor to checking-for-cart-instructions-changes-to-applycartlineschange()Changes to applyCartLinesChange()

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

Anchor to checking-for-cart-instructions-changes-to-applymetafieldchange()Changes to applyMetafieldChange()

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

Anchor to checking-for-cart-instructions-changes-to-applynotechange()Changes to applyNoteChange()

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

Migrating applyAttributeChange()

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 (

Loyalty points are unavailable

</Banner>

);

}

Examples

Migrating applyAttributeChange()

React

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

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