Attributes

The API for interacting with cart and checkout attributes.

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

StandardApi

The base API object provided to `purchase` extension targets.

Docs_Standard_AttributesApi

attributes

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

Attribute

key

The key for the attribute.

value

The value for the attribute.

CheckoutApi

The API object provided to `purchase.checkout` extension targets.

Docs_Checkout_AttributesApi

applyAttributeChange

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`](/docs/api/checkout-ui-extensions/apis/attributes#standardapi-propertydetail-attributes) property. > Note: This method will return an error if the [cart instruction](/docs/api/checkout-ui-extensions/apis/cart-instructions#standardapi-propertydetail-instructions) `attributes.canUpdateAttributes` is false, or the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.

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

type

The type of the `AttributeUpdateChange` API.

value

Value for the attribute to add or update

Attribute

key

The key for the attribute.

value

The value for the attribute.

AttributeChangeResult

AttributeChangeResultSuccess | AttributeChangeResultError

AttributeChangeResultSuccess

The returned result of a successful update to an attribute.

type

The type of the `AttributeChangeResultSuccess` API.

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.

type

The type of the `AttributeChangeResultError` API.

useApplyAttributeChange

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

UseApplyAttributeChangeGeneratedType

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

Returns: (change: AttributeChange) => Promise

export function useApplyAttributeChange< Target extends RenderExtensionTarget = RenderExtensionTarget, >(): (change: AttributeChange) => Promise { const api = useApi(); if ('applyAttributeChange' in api) { return api.applyAttributeChange; } throw new ExtensionHasNoMethodError( 'applyAttributeChange', api.extension.target, ); }

AttributeChange

key

Key of the attribute to add or update

type

The type of the `AttributeUpdateChange` API.

value

Value for the attribute to add or update

Attribute

key

The key for the attribute.

value

The value for the attribute.

AttributeChangeResult

AttributeChangeResultSuccess | AttributeChangeResultError

AttributeChangeResultSuccess

The returned result of a successful update to an attribute.

type

The type of the `AttributeChangeResultSuccess` API.

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.

type

The type of the `AttributeChangeResultError` API.

useAttributes

Returns the proposed `attributes` applied to the checkout.

UseAttributesGeneratedType

Returns the proposed `attributes` applied to the checkout.

Returns: Attribute[] | undefined

export function useAttributes< Target extends RenderExtensionTarget = RenderExtensionTarget, >(): Attribute[] | undefined { return useSubscription(useApi().attributes); }

Attribute

key

The key for the attribute.

value

The value for the attribute.

useAttributeValues

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

UseAttributeValuesGeneratedType

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

Returns: (string | undefined)[]

Params:

keys: string[]

export function useAttributeValues< Target extends RenderExtensionTarget = RenderExtensionTarget, >(keys: string[]): (string | undefined)[] { const attributes = useAttributes(); if (!attributes?.length) { return []; } return keys.map((key) => { const attribute = attributes.find((attribute) => attribute.key === key); return attribute?.value; }); }

Related

• Targets
• Components
• Configuration
• Tutorials