Skip to main content

Cart Instructions
API

Instructions used to create the checkout.

Anchor to standardapiStandardApi

The base API object provided to purchase extension targets.

Anchor to instructions
instructions
StatefulRemoteSubscribable<>
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.

Was this section helpful?

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.

Was this section helpful?

Discounts

import {
Banner,
Button,
useApplyDiscountCodeChange,
useInstructions,
reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
const applyDiscountCodeChange =
useApplyDiscountCodeChange();
const instructions = useInstructions();

if (
instructions.discounts.canUpdateDiscountCodes
) {
return (
<Button
onPress={() =>
applyDiscountCodeChange({
type: 'addDiscountCode',
code: 'FREE_SHIPPING',
})
}
>
Apply your loyalty discount
</Button>
);
} else {
return (
<Banner status="warning">
Loyalty discounts are unavailable
</Banner>
);
}
}

Anchor to examplesExamples

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

Anchor to example-attributesAttributes

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

Anchor to example-deliveryDelivery

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

Anchor to example-discountsDiscounts

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

Anchor to example-linesLines

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

Anchor to example-metafieldsMetafields

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

Anchor to example-notesNotes

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

Was this section helpful?

Attributes

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

Anchor to relatedRelated

ReferenceTargets
ReferenceComponents
ReferenceConfiguration
LearnTutorials