--- title: Attributes API description: The API for interacting with cart and checkout attributes. api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/attributes-api md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/attributes-api.md --- # Attributes API The API for interacting with cart and checkout attributes. ### Support Targets (33) ### Supported targets * purchase.​address-autocomplete.​format-suggestion * purchase.​address-autocomplete.​suggest * purchase.​checkout.​actions.​render-before * purchase.​checkout.​block.​render * purchase.​checkout.​cart-line-item.​render-after * purchase.​checkout.​cart-line-list.​render-after * purchase.​checkout.​chat.​render * purchase.​checkout.​contact.​render-after * purchase.​checkout.​delivery-address.​render-after * purchase.​checkout.​delivery-address.​render-before * purchase.​checkout.​footer.​render-after * purchase.​checkout.​header.​render-after * purchase.​checkout.​payment-method-list.​render-after * purchase.​checkout.​payment-method-list.​render-before * purchase.​checkout.​pickup-location-list.​render-after * purchase.​checkout.​pickup-location-list.​render-before * purchase.​checkout.​pickup-location-option-item.​render-after * purchase.​checkout.​pickup-point-list.​render-after * purchase.​checkout.​pickup-point-list.​render-before * purchase.​checkout.​reductions.​render-after * purchase.​checkout.​reductions.​render-before * purchase.​checkout.​shipping-option-item.​details.​render * purchase.​checkout.​shipping-option-item.​render-after * purchase.​checkout.​shipping-option-list.​render-after * purchase.​checkout.​shipping-option-list.​render-before * purchase.​thank-you.​announcement.​render * purchase.​thank-you.​block.​render * purchase.​thank-you.​cart-line-item.​render-after * purchase.​thank-you.​cart-line-list.​render-after * purchase.​thank-you.​chat.​render * purchase.​thank-you.​customer-information.​render-after * purchase.​thank-you.​footer.​render-after * purchase.​thank-you.​header.​render-after ## StandardApi The base API object provided to `purchase` extension targets. * **attributes** **SubscribableSignalLike\** **required** The custom key-value attributes attached to the cart or checkout. These are set by the buyer or by an extension using `applyAttributeChange()`. The list is empty if no attributes have been added. ### SubscribableSignalLike Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends \`ReadonlySignalLike\` with deprecated fields that are still supported for backwards compatibility. * current The current value of the signal. Equivalent to \`.value\`, accessing this property subscribes to changes when used in a reactive context. ```ts T ``` * destroy Cleans up the subscription and releases any resources held by this signal. After calling \`destroy()\`, the signal stops receiving updates from the main thread. ```ts () => Promise ``` * subscribe Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value. ```ts (fn: (value: T) => void) => () => void ``` * value The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup. ```ts T ``` ### Attribute * key The identifier for the attribute. Each key must be unique within the set of attributes on the cart or checkout. If you call \`applyAttributeChange()\` with a key that already exists, then the existing value is replaced. ```ts string ``` * value The value associated with the attribute key. This is a freeform string that can store any information the buyer or app provides. ```ts string ``` ## CheckoutApi The API object provided to `purchase.checkout` extension targets. * **applyAttributeChange** **(change: AttributeChange) => Promise\** **required** **deprecated** Updates or removes an attribute on the cart and checkout. On success, the [`attributes`](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/apis/attributes#standardapi-propertydetail-attributes) property updates to reflect the change. **Note:** This method returns an error if the \cart instruction\ \\attributes.can\Update\Attributes\\ is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay. **Deprecated:** Use cart metafields instead. ### AttributeChange The input for \`applyAttributeChange()\`. Pass either an \`AttributeUpdateChange\` (with \`type: 'updateAttribute'\`) to set the attribute or an \`AttributeRemoveChange\` (with \`type: 'removeAttribute'\`) to delete it. ```ts AttributeUpdateChange | AttributeRemoveChange ``` ### AttributeUpdateChange Updates an attribute on the cart and checkout. If an attribute with the provided key doesn't already exist, then it gets created. * key The key of the attribute to add or update. If an attribute with this key already exists, then its value is replaced. ```ts string ``` * type Identifies this as an attribute update or creation. Set this when creating a change to add or replace an attribute value. ```ts 'updateAttribute' ``` * value The new value for the attribute. ```ts string ``` ### AttributeRemoveChange Removes an attribute from the checkout. Pass this to \`applyAttributeChange()\` to delete an attribute by key. If the key doesn't exist, then the change has no effect. * key The key of the attribute to remove. ```ts string ``` * type Identifies this as an attribute removal. Set this when creating a change to delete an attribute by key. ```ts 'removeAttribute' ``` ### AttributeChangeResult The result of calling \`applyAttributeChange()\`. Use the \`type\` property to determine whether the change succeeded or failed. ```ts AttributeChangeResultSuccess | AttributeChangeResultError ``` ### AttributeChangeResultSuccess The result of a successful attribute change. The \`type\` property is \`'success'\`. * type Indicates that the attribute change was applied successfully. ```ts 'success' ``` ### AttributeChangeResultError The result of a failed attribute change. Check the \`message\` property for details about what went wrong. * message A message that explains the error. This message is useful for debugging. It isn't localized and shouldn't be displayed to the buyer. ```ts string ``` * type Indicates that the attribute change couldn't be applied. Check the \`message\` property for details. ```ts 'error' ``` ## use​Apply​Attribute​Change() Returns a function to mutate the `attributes` property of the checkout. ### Returns * **(change: AttributeChange) => Promise\** ## use​Attributes() Returns the proposed `attributes` applied to the checkout. ### Returns * **Attribute\[]** ## use​Attribute​Values(**[keys](#useattributevalues-propertydetail-keys)**​) Returns the values for the specified `attributes` applied to the checkout. ### Parameters * **keys** **string\[]** **required** An array of attribute keys. ### Returns * **(string | undefined)\[]** Examples ### Examples * #### Attribute values ##### Preact ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useAttributeValues} from '@shopify/ui-extensions/checkout/preact'; export default function extension() { render(, document.body); } function Extension() { const [buyerSelectedFreeTShirt, tshirtSize] = useAttributeValues([ 'buyerSelectedFreeTShirt', 'tshirtSize', ]); if (Boolean(buyerSelectedFreeTShirt) === true) { return ( You selected a free t-shirt, size:{' '} {tshirtSize} ); } return null; } ``` * #### Applying changes to attributes ##### Description You can add or remove cart and checkout attributes by using the \`applyAttributeChange\` API. ##### Preact ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useAttributeValues} from '@shopify/ui-extensions/checkout/preact'; export default function extension() { render(, document.body); } function Extension() { const [giftWrapValue] = useAttributeValues([ 'giftWrap', ]); const giftWrap = Boolean(giftWrapValue); async function toggleGiftWrap() { const result = giftWrap ? await shopify.applyAttributeChange({ type: 'removeAttribute', key: 'giftWrap', }) : await shopify.applyAttributeChange({ type: 'updateAttribute', key: 'giftWrap', value: 'true', }); if (result.type === 'error') { console.error(result.message); } } return ( Gift wrapping:{' '} {giftWrap ? 'Added' : 'Not set'} {giftWrap ? 'Remove gift wrap' : 'Add gift wrap'} ); } ``` ## Related [Reference - Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets) [Reference - Components](https://shopify.dev/docs/api/checkout-ui-extensions/components) [Reference - Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) [Learn - Tutorials](https://shopify.dev/apps/checkout)