Skip to main content

Attributes
API

The API for interacting with cart and checkout attributes.

Anchor to standardapiStandardApi

The base API object provided to purchase extension targets.

Anchor to attributes
attributes
StatefulRemoteSubscribable<[] | undefined>
required

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

Was this section helpful?

Anchor to checkoutapiCheckoutApi

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.

Anchor to useApplyAttributeChange-returnsReturns

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

Anchor to useAttributes
useAttributes()

Returns the proposed attributes applied to the checkout.

Anchor to useAttributes-returnsReturns

[] | undefined
Was this section helpful?

Anchor to useAttributeValues
useAttributeValues(
keys
)

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

Anchor to useAttributeValues-parametersParameters

Anchor to keys
keys
string[]
required

An array of attribute keys.

Anchor to useAttributeValues-returnsReturns

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

Anchor to examplesExamples

Anchor to example-applying-changes-to-attributesApplying changes to attributes

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

Anchor to relatedRelated

ReferenceTargets
ReferenceComponents
ReferenceConfiguration
LearnTutorials