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.
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 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. |
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.
Anchor to checking-for-cart-instructions-changes-to-applyattributechange()Changes to applyAttributeChange()
Check before calling
.
Anchor to checking-for-cart-instructions-changes-to-applyshippingaddresschange()Changes to applyShippingAddressChange()
Check before calling
. 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 before calling
.
Anchor to checking-for-cart-instructions-changes-to-applycartlineschange()Changes to applyCartLinesChange()
Check or
or
before calling
.
Anchor to checking-for-cart-instructions-changes-to-applymetafieldchange()Changes to applyMetafieldChange()
Check or
before calling
if you are working with cart metafields.
Anchor to checking-for-cart-instructions-changes-to-applynotechange()Changes to applyNoteChange()
Check before calling
.
Migrating applyAttributeChange()
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', ), ); } }, );