Skip to main content

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.


Anchor to instruction-checkingRequired instruction checking

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

Extension APIAs 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

Anchor to migrating-apisChecking for cart instructions

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

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

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

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

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

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

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 (
<Banner status="warning">
Loyalty points are unavailable
</Banner>
);
}
}