Skip to main content

Attributes
API

The API for interacting with cart and checkout attributes.

The base API object provided to purchase extension targets.

StatefulRemoteSubscribable<[] | undefined>
required

The custom attributes left by the customer to the merchant, either in their cart or during checkout.

Was this section helpful?

The API object provided to purchase.checkout extension targets.

Anchor to applyAttributeChange
applyAttributeChange
(change: ) => Promise<>
required

Performs an update on an attribute attached to the cart and checkout. If successful, this mutation results in an update to the value retrieved through the attributes property.

Note

This method will return an error if the cart instruction attributes.canUpdateAttributes is false, or the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.

Was this section helpful?

Anchor to useApplyAttributeChange
useApplyAttributeChange()

Returns a function to mutate the attributes property of the checkout.

(change: ) => Promise<>
Was this section helpful?

Returns the proposed attributes applied to the checkout.

[] | undefined
Was this section helpful?

Returns the values for the specified attributes applied to the checkout.

string[]
required

An array of attribute keys.

(string | undefined)[]
Was this section helpful?

Attribute values

import {
Text,
reactExtension,
useAttributeValues,
} from '@shopify/ui-extensions-react/checkout';

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

function Extension() {
const [buyerSelectedFreeTShirt, tshirtSize] =
useAttributeValues([
'buyerSelectedFreeTShirt',
'tshirtSize',
]);

if (Boolean(buyerSelectedFreeTShirt) === true) {
return (
<Text>
You selected a free t-shirt, size:{' '}
{tshirtSize}
</Text>
);
}

return null;
}

You can add or remove cart and checkout attributes by using the applyAttributeChange API.

Was this section helpful?

Applying changes to attributes

import {
reactExtension,
BlockStack,
Button,
Text,
useAttributeValues,
useApplyAttributeChange,
useInstructions,
} from '@shopify/ui-extensions-react/checkout';

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

function Extension() {
const [giftWrapValue] = useAttributeValues([
'giftWrap',
]);
const giftWrap = Boolean(giftWrapValue);
const applyAttributeChange =
useApplyAttributeChange();
const instructions = useInstructions();

async function toggleGiftWrap() {
const result = giftWrap
? await applyAttributeChange({
type: 'removeAttribute',
key: 'giftWrap',
})
: await applyAttributeChange({
type: 'updateAttribute',
key: 'giftWrap',
value: 'true',
});
if (result.type === 'error') {
console.error(result.message);
}
}

return (
<BlockStack spacing="tight">
<Text>
Gift wrapping:{' '}
{giftWrap ? 'Added' : 'Not set'}
</Text>
<Button
onPress={toggleGiftWrap}
disabled={
!instructions.attributes
.canUpdateAttributes
}
>
{giftWrap
? 'Remove gift wrap'
: 'Add gift wrap'}
</Button>
</BlockStack>
);
}