Choose a version:

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 <[]> required: The custom attributes left by the customer to the merchant, either in their cart or during checkout.

SubscribableSignalLike

Represents a read-only value managed on the main thread that an extension can subscribe to. Example: Checkout uses this to manage the state of an object and communicate state changes to extensions running in a sandboxed web worker. This interface is compatible with [Preact's ReadonlySignal](https://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709). Some fields are deprecated but still supported for backwards compatibility. In version 2025-10, [`StatefulRemoteSubscribable`](https://github.com/Shopify/remote-dom/blob/03929aa8418a89d41d294005f219837582718df8/packages/async-subscription/src/types.ts#L17) was replaced with `ReadonlySignalLike`. Checkout will remove the old fields some time in the future.

current
```
T
```
destroy
```
() => Promise<void>
```
subscribe
```
(fn: (value: T) => void) => () => void
```
value
```
T
```

export interface SubscribableSignalLike<T> extends ReadonlySignalLike<T> { /** * @deprecated Use `.value` instead. */ readonly current: T; /** * @deprecated No longer needed. Use Preact Signal management instead. */ destroy(): Promise<void>; }

Attribute

key
The key for the attribute.
```
string
```
value
The value for the attribute.
```
string
```

export interface Attribute { /** * The key for the attribute. */ key: string; /** * The value for the attribute. */ value: string; }

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 or Google Pay.

AttributeChange

AttributeUpdateChange | AttributeRemoveChange

AttributeUpdateChange

Updates an attribute on the order. If an attribute with the provided key does not already exist, it gets created.

key
Key of the attribute to add or update
```
string
```
type
The type of the `AttributeUpdateChange` API.
```
'updateAttribute'
```
value
Value for the attribute to add or update
```
string
```

export interface AttributeUpdateChange { /** * The type of the `AttributeUpdateChange` API. */ type: 'updateAttribute'; /** * Key of the attribute to add or update */ key: string; /** * Value for the attribute to add or update */ value: string; }

AttributeRemoveChange

Removes an attribute on the order if an attribute with the provided key already exists.

key
Key of the attribute to remove
```
string
```
type
The type of the `AttributeRemoveChange` API.
```
'removeAttribute'
```

export interface AttributeRemoveChange { /** * The type of the `AttributeRemoveChange` API. */ type: 'removeAttribute'; /** * Key of the attribute to remove */ key: string; }

AttributeChangeResult

AttributeChangeResultSuccess | AttributeChangeResultError

AttributeChangeResultSuccess

The returned result of a successful update to an attribute.

type
The type of the `AttributeChangeResultSuccess` API.
```
'success'
```

export interface AttributeChangeResultSuccess { /** * The type of the `AttributeChangeResultSuccess` API. */ type: 'success'; }

AttributeChangeResultError

The returned result of an unsuccessful update to an attribute with a message detailing the type of error that occurred.

message
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.
```
string
```
type
The type of the `AttributeChangeResultError` API.
```
'error'
```

export interface AttributeChangeResultError { /** * The type of the `AttributeChangeResultError` API. */ type: 'error'; /** * A message that explains the error. This message is useful for debugging. * It is **not** localized, and therefore should not be presented directly * to the buyer. */ message: string; }

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<>

AttributeChange

AttributeUpdateChange | AttributeRemoveChange

AttributeUpdateChange

Updates an attribute on the order. If an attribute with the provided key does not already exist, it gets created.

key
Key of the attribute to add or update
```
string
```
type
The type of the `AttributeUpdateChange` API.
```
'updateAttribute'
```
value
Value for the attribute to add or update
```
string
```

export interface AttributeUpdateChange { /** * The type of the `AttributeUpdateChange` API. */ type: 'updateAttribute'; /** * Key of the attribute to add or update */ key: string; /** * Value for the attribute to add or update */ value: string; }

AttributeRemoveChange

Removes an attribute on the order if an attribute with the provided key already exists.

key
Key of the attribute to remove
```
string
```
type
The type of the `AttributeRemoveChange` API.
```
'removeAttribute'
```

export interface AttributeRemoveChange { /** * The type of the `AttributeRemoveChange` API. */ type: 'removeAttribute'; /** * Key of the attribute to remove */ key: string; }

AttributeChangeResult

AttributeChangeResultSuccess | AttributeChangeResultError

AttributeChangeResultSuccess

The returned result of a successful update to an attribute.

type
The type of the `AttributeChangeResultSuccess` API.
```
'success'
```

export interface AttributeChangeResultSuccess { /** * The type of the `AttributeChangeResultSuccess` API. */ type: 'success'; }

AttributeChangeResultError

The returned result of an unsuccessful update to an attribute with a message detailing the type of error that occurred.

message
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.
```
string
```
type
The type of the `AttributeChangeResultError` API.
```
'error'
```

export interface AttributeChangeResultError { /** * The type of the `AttributeChangeResultError` API. */ type: 'error'; /** * A message that explains the error. This message is useful for debugging. * It is **not** localized, and therefore should not be presented directly * to the buyer. */ message: string; }

Was this section helpful?

Anchor to useAttributes
useAttributes()

Returns the proposed attributes applied to the checkout.

Anchor to useAttributes-returnsReturns

[]

Attribute

key
The key for the attribute.
```
string
```
value
The value for the attribute.
```
string
```

export interface Attribute { /** * The key for the attribute. */ key: string; /** * The value for the attribute. */ value: string; }

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

Preact

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

import {useAttributeValues} from '@shopify/ui-extensions/checkout/preact';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

const [buyerSelectedFreeTShirt, tshirtSize] =

useAttributeValues([

'buyerSelectedFreeTShirt',

'tshirtSize',

]);

if (Boolean(buyerSelectedFreeTShirt) === true) {

return (

<s-text>

You selected a free t-shirt, size:{' '}

{tshirtSize}

</s-text>

);

}

return null;

}

Examples

Attribute values

Preact

import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useAttributeValues} from '@shopify/ui-extensions/checkout/preact'; export default function extension() { render(<Extension />, document.body); } function Extension() { const [buyerSelectedFreeTShirt, tshirtSize] = useAttributeValues([ 'buyerSelectedFreeTShirt', 'tshirtSize', ]); if (Boolean(buyerSelectedFreeTShirt) === true) { return ( <s-text> You selected a free t-shirt, size:{' '} {tshirtSize} </s-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

Preact

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

import {useAttributeValues} from '@shopify/ui-extensions/checkout/preact';

export default function extension() {

render(<Extension />, 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 (

<s-stack>

<s-text>

Gift wrapping:{' '}

{giftWrap ? 'Added' : 'Not set'}

</s-text>

<s-button

onClick={toggleGiftWrap}

disabled={

!shopify.instructions.value.attributes

.canUpdateAttributes

}

{giftWrap

? 'Remove gift wrap'

: 'Add gift wrap'}

</s-button>

</s-stack>

);

}

Examples

Applying changes to attributes

Description

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

Preact

import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useAttributeValues} from '@shopify/ui-extensions/checkout/preact'; export default function extension() { render(<Extension />, 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 ( <s-stack> <s-text> Gift wrapping:{' '} {giftWrap ? 'Added' : 'Not set'} </s-text> <s-button onClick={toggleGiftWrap} disabled={ !shopify.instructions.value.attributes .canUpdateAttributes } > {giftWrap ? 'Remove gift wrap' : 'Add gift wrap'} </s-button> </s-stack> ); }