Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Authentication State API

The Authentication State API provides the buyer's current authentication status in customer accounts. Use it to conditionally render content based on whether the buyer is fully signed in or viewing through a tokenized link.

Anchor to Use casesUse cases

Conditional content rendering: Show different UI depending on whether the buyer is fully authenticated or viewing the page through a pre-authenticated link.
Prompt for sign-in: Detect when a buyer is pre-authenticated and display a message encouraging them to sign in for a richer experience.
Protect sensitive data: Only display detailed customer information when the buyer is fully authenticated.

Support

Targets (10)

Supported targets

Anchor to PropertiesProperties

The Authentication State API object provides the buyer's authentication state. Access the following properties on the API object to read authentication data.

Anchor to authenticationState authenticationState StatefulRemoteSubscribable<> required: The buyer's current authentication state on the Order status page. The value is either 'fully_authenticated' (the buyer is logged in) or 'pre_authenticated' (the buyer is viewing through a tokenized link).

AuthenticationState

The buyer’s authentication state on the **Order status** page: - `'fully_authenticated'`: The buyer has logged in to their customer account. - `'pre_authenticated'`: The buyer accessed the page through a tokenized link without logging in.

'fully_authenticated' | 'pre_authenticated'

Examples

import {

reactExtension,

useAuthenticationState,

} from '@shopify/ui-extensions-react/customer-account';

import {Banner, Text} from '@shopify/ui-extensions/customer-account';

export default reactExtension(

'customer-account.order-status.block.render',

() => <Extension />,

);

function Extension() {

const authState = useAuthenticationState();

return (

<Text>

{authState === 'fully_authenticated'

? 'You are fully logged in.'

: 'You are viewing this page through a shared link.'}

</Text>

</Banner>

);

}

Examples

Description

Read the buyer's authentication state and display whether they're fully authenticated or pre-authenticated. This example uses the `useAuthenticationState` hook to render the current status as text.

React

import {
  reactExtension,
  useAuthenticationState,
} from '@shopify/ui-extensions-react/customer-account';
import {Banner, Text} from '@shopify/ui-extensions/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  const authState = useAuthenticationState();
  return (
    <Banner status={authState === 'fully_authenticated' ? 'success' : 'warning'}>
      <Text>
        {authState === 'fully_authenticated'
          ? 'You are fully logged in.'
          : 'You are viewing this page through a shared link.'}
      </Text>
    </Banner>
  );
}

TS

import {extension, Banner, Text} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const authState = api.authenticationState.current;
    const banner = root.createComponent(
      Banner,
      {status: authState === 'fully_authenticated' ? 'success' : 'warning'},
    );
    banner.appendChild(
      root.createComponent(
        Text, {},
        authState === 'fully_authenticated'
          ? 'You are fully logged in.'
          : 'You are viewing this page through a shared link.',
      ),
    );
    root.appendChild(banner);
  },
);

Description

Show different content depending on whether the buyer is fully authenticated or pre-authenticated. This example uses `useAuthenticationState` to conditionally render a full dashboard or a limited view.

React

import {
  reactExtension,
  useAuthenticationState,
} from '@shopify/ui-extensions-react/customer-account';
import {BlockStack, Text, Link} from '@shopify/ui-extensions/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  const authState = useAuthenticationState();

  if (authState !== 'fully_authenticated') {
    return <Text appearance="subdued">Log in to see personalized recommendations.</Text>;
  }

  return (
    <BlockStack>
      <Text emphasis="bold">Recommended for you</Text>
      <Link to="https://example.com/recommendations">View recommendations</Link>
    </BlockStack>
  );
}

TS

import {extension, BlockStack, Text, Link} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const authState = api.authenticationState.current;

    if (authState !== 'fully_authenticated') {
      root.appendChild(
        root.createComponent(Text, {appearance: 'subdued'}, 'Log in to see personalized recommendations.'),
      );
      return;
    }

    const stack = root.createComponent(BlockStack, {});
    stack.appendChild(root.createComponent(Text, {emphasis: 'bold'}, 'Recommended for you'));
    stack.appendChild(root.createComponent(Link, {to: 'https://example.com/recommendations'}, 'View recommendations'));
    root.appendChild(stack);
  },
);

Description

Check the authentication state before allowing the buyer to perform sensitive actions. This example uses `useAuthenticationState` to gate a button behind full authentication.

React

import React, {useState} from 'react';
import {
  reactExtension,
  useAuthenticationState,
  useApi,
} from '@shopify/ui-extensions-react/customer-account';
import {Banner, Button, Text} from '@shopify/ui-extensions/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  const authState = useAuthenticationState();
  const {requireLogin} = useApi<'customer-account.order-status.block.render'>();
  const [loading, setLoading] = useState(false);

  if (authState === 'fully_authenticated') {
    return <Button onPress={() => {}}>Manage subscription</Button>;
  }

  return (
    <Banner status="warning">
      <Text>Log in to manage your subscription.</Text>
      <Button
        disabled={loading}
        onPress={async () => {
          setLoading(true);
          await requireLogin();
          setLoading(false);
        }}
      >
        Log in
      </Button>
    </Banner>
  );
}

TS

import {extension, Banner, Button, Text} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const authState = api.authenticationState.current;

    if (authState === 'fully_authenticated') {
      root.appendChild(root.createComponent(Button, {onPress: () => {}}, 'Manage subscription'));
      return;
    }

    const banner = root.createComponent(Banner, {status: 'warning'});
    banner.appendChild(root.createComponent(Text, {}, 'Log in to manage your subscription.'));
    banner.appendChild(
      root.createComponent(Button, {onPress: async () => { await api.requireLogin(); }}, 'Log in'),
    );
    root.appendChild(banner);
  },
);

Anchor to Best practicesBest practices

Gate sensitive actions behind full authentication: Use the authentication state to restrict actions like editing order details to fully authenticated buyers.
Provide fallback content for pre-authenticated buyers: Pre-authenticated buyers access the page through a tokenized link. Show limited information and offer a sign-in prompt for additional actions.

Anchor to LimitationsLimitations

The authentication state is read-only. You can't change the buyer's authentication level directly — use the Require Login API to prompt them to log in.
Pre-authenticated buyers may have limited access to protected customer data, which can cause some API properties to return undefined.

Was this page helpful?