Choose a version:

Buyer Journey
API

The API for interacting with the buyer journey.

Anchor to standardapiStandardApi

The base API object provided to purchase, and customer-account.order-status extension targets.

Anchor to buyerJourney buyerJourney required: Provides details on the buyer's progression through the checkout.

See buyer journey examples for more information.

Docs_Standard_BuyerJourneyApi

buyerJourney
Provides details on the buyer's progression through the checkout. See [buyer journey](/docs/api/checkout-ui-extensions/apis/buyer-journey#examples) examples for more information.
```
BuyerJourney
```

export interface Docs_Standard_BuyerJourneyApi
  extends Pick<StandardApi, 'buyerJourney'> {}

BuyerJourney

Provides details on the buyer's progression through the checkout.

intercept
Installs a function for intercepting and preventing progress on checkout. This returns a promise that resolves to a teardown function. Calling the teardown function will remove the interceptor. To block checkout progress, you must set the [block_progress](/docs/api/checkout-ui-extensions/configuration#block-progress) capability in your extension's configuration.
```
(interceptor: Interceptor) => Promise<() => void>
```
completed
This subscribable value will be true if the buyer completed submitting their order. For example, when viewing the **Order status** page after submitting payment, the buyer will have completed their order.
```
StatefulRemoteSubscribable<boolean>
```

export interface BuyerJourney {
  /**
   * Installs a function for intercepting and preventing progress on checkout.
   *
   * This returns a promise that resolves to a teardown function. Calling the
   * teardown function will remove the interceptor.
   *
   * To block checkout progress, you must set the [block_progress](/docs/api/checkout-ui-extensions/configuration#block-progress)
   * capability in your extension's configuration.
   */
  intercept(interceptor: Interceptor): Promise<() => void>;

  /**
   * This subscribable value will be true if the buyer completed submitting their order.
   *
   * For example, when viewing the **Order status** page after submitting payment, the buyer will have completed their order.
   */
  completed: StatefulRemoteSubscribable<boolean>;
}

Interceptor

A function for intercepting and preventing navigation on checkout. You can block navigation by returning an object with `{behavior: 'block', reason: InvalidResultReason.InvalidExtensionState, errors?: ValidationErrors[]}`. If you do, then you're expected to also update some part of your UI to reflect the reason why navigation was blocked, either by targeting checkout UI fields, passing errors to the page level or rendering the errors in your extension.

(
  interceptorProps: InterceptorProps,
) => InterceptorRequest | Promise<InterceptorRequest>

InterceptorProps

canBlockProgress
Whether the interceptor has the capability to block a buyer's progress through checkout. This ability might be granted by a merchant in differing checkout contexts.
```
boolean
```

export interface InterceptorProps {
  /**
   * Whether the interceptor has the capability to block a buyer's progress through
   * checkout. This ability might be granted by a merchant in differing checkout contexts.
   */
  canBlockProgress: boolean;
}

InterceptorRequest

InterceptorRequestAllow | InterceptorRequestBlock

InterceptorRequestAllow

behavior
Indicates that the interceptor will allow the buyer's journey to continue.
```
"allow"
```
perform
This callback is called when all interceptors finish. We recommend setting errors or reasons for blocking at this stage, so that all the errors in the UI show up at once.
```
(result: InterceptorResult) => void | Promise<void>
```

interface InterceptorRequestAllow {
  /**
   * Indicates that the interceptor will allow the buyer's journey to continue.
   */
  behavior: 'allow';

  /**
   * This callback is called when all interceptors finish. We recommend
   * setting errors or reasons for blocking at this stage, so that all the errors in
   * the UI show up at once.
   * @param result InterceptorResult with behavior as either 'allow' or 'block'
   */
  perform?(result: InterceptorResult): void | Promise<void>;
}

InterceptorResult

InterceptorResultAllow | InterceptorResultBlock

InterceptorResultAllow

behavior
Indicates that the buyer was allowed to progress through checkout.
```
"allow"
```

interface InterceptorResultAllow {
  /**
   * Indicates that the buyer was allowed to progress through checkout.
   */
  behavior: 'allow';
}

InterceptorResultBlock

behavior
Indicates that some part of the checkout UI intercepted and prevented the buyer’s progress. The buyer typically needs to take some action to resolve this issue and to move on to the next step.
```
"block"
```

interface InterceptorResultBlock {
  /**
   * Indicates that some part of the checkout UI intercepted and prevented
   * the buyer’s progress. The buyer typically needs to take some action
   * to resolve this issue and to move on to the next step.
   */
  behavior: 'block';
}

InterceptorRequestBlock

behavior
Indicates that the interceptor will block the buyer's journey from continuing.
```
"block"
```
reason
The reason for blocking the interceptor request. This value isn't presented to the buyer, so it doesn't need to be localized. The value is used only for Shopify’s own internal debugging and metrics.
```
string
```
errors
Used to pass errors to the checkout UI, outside your extension's UI boundaries.
```
ValidationError[]
```
perform
This callback is called when all interceptors finish. We recommend setting errors or reasons for blocking at this stage, so that all the errors in the UI show up at once.
```
(result: InterceptorResult) => void | Promise<void>
```

interface InterceptorRequestBlock {
  /**
   * Indicates that the interceptor will block the buyer's journey from continuing.
   */
  behavior: 'block';

  /**
   * The reason for blocking the interceptor request. This value isn't presented to
   * the buyer, so it doesn't need to be localized. The value is used only for Shopify’s
   * own internal debugging and metrics.
   */
  reason: string;

  /**
   * Used to pass errors to the checkout UI, outside your extension's UI boundaries.
   */
  errors?: ValidationError[];

  /**
   * This callback is called when all interceptors finish. We recommend
   * setting errors or reasons for blocking at this stage, so that all the errors in
   * the UI show up at once.
   * @param result InterceptorResult with behavior as either 'allow' or 'block'
   */
  perform?(result: InterceptorResult): void | Promise<void>;
}

ValidationError

message
Error message to be displayed to the buyer.
```
string
```
target
The checkout UI field that the error is associated with. Example: `$.cart.deliveryGroups[0].deliveryAddress.countryCode` See the [supported targets](/docs/api/functions/reference/cart-checkout-validation/graphql#supported-targets) for more information.
```
string
```

export interface ValidationError {
  /**
   * Error message to be displayed to the buyer.
   */
  message: string;
  /**
   * The checkout UI field that the error is associated with.
   *
   * Example: `$.cart.deliveryGroups[0].deliveryAddress.countryCode`
   *
   * See the [supported targets](/docs/api/functions/reference/cart-checkout-validation/graphql#supported-targets)
   * for more information.
   */
  target?: string;
}

Was this section helpful?

Anchor to useBuyerJourney
useBuyerJourney()

Returns the buyerJourney details on buyer progression in checkout.

Anchor to useBuyerJourney-returnsReturns

BuyerJourney

intercept (interceptor: ) => Promise<() => void>: Installs a function for intercepting and preventing progress on checkout.

This returns a promise that resolves to a teardown function. Calling the teardown function will remove the interceptor.

To block checkout progress, you must set the block_progress capability in your extension's configuration.
completed StatefulRemoteSubscribable<boolean>: This subscribable value will be true if the buyer completed submitting their order.

For example, when viewing the Order status page after submitting payment, the buyer will have completed their order.

UseBuyerJourneyGeneratedType

Returns the `buyerJourney` details on buyer progression in checkout.

BuyerJourney

BuyerJourney

export function useBuyerJourney<
  Target extends RenderExtensionTarget = RenderExtensionTarget,
>(): BuyerJourney {
  const api = useApi<Target>();

  if ('buyerJourney' in api) {
    return api.buyerJourney;
  }

  throw new ExtensionHasNoMethodError(
    'applyAttributeChange',
    api.extension.target,
  );
}

BuyerJourney

Provides details on the buyer's progression through the checkout.

intercept
Installs a function for intercepting and preventing progress on checkout. This returns a promise that resolves to a teardown function. Calling the teardown function will remove the interceptor. To block checkout progress, you must set the [block_progress](/docs/api/checkout-ui-extensions/configuration#block-progress) capability in your extension's configuration.
```
(interceptor: Interceptor) => Promise<() => void>
```
completed
This subscribable value will be true if the buyer completed submitting their order. For example, when viewing the **Order status** page after submitting payment, the buyer will have completed their order.
```
StatefulRemoteSubscribable<boolean>
```

export interface BuyerJourney {
  /**
   * Installs a function for intercepting and preventing progress on checkout.
   *
   * This returns a promise that resolves to a teardown function. Calling the
   * teardown function will remove the interceptor.
   *
   * To block checkout progress, you must set the [block_progress](/docs/api/checkout-ui-extensions/configuration#block-progress)
   * capability in your extension's configuration.
   */
  intercept(interceptor: Interceptor): Promise<() => void>;

  /**
   * This subscribable value will be true if the buyer completed submitting their order.
   *
   * For example, when viewing the **Order status** page after submitting payment, the buyer will have completed their order.
   */
  completed: StatefulRemoteSubscribable<boolean>;
}

Interceptor

(
  interceptorProps: InterceptorProps,
) => InterceptorRequest | Promise<InterceptorRequest>

InterceptorProps

canBlockProgress
Whether the interceptor has the capability to block a buyer's progress through checkout. This ability might be granted by a merchant in differing checkout contexts.
```
boolean
```

export interface InterceptorProps {
  /**
   * Whether the interceptor has the capability to block a buyer's progress through
   * checkout. This ability might be granted by a merchant in differing checkout contexts.
   */
  canBlockProgress: boolean;
}

InterceptorRequest

InterceptorRequestAllow | InterceptorRequestBlock

InterceptorRequestAllow

behavior
Indicates that the interceptor will allow the buyer's journey to continue.
```
"allow"
```
perform
This callback is called when all interceptors finish. We recommend setting errors or reasons for blocking at this stage, so that all the errors in the UI show up at once.
```
(result: InterceptorResult) => void | Promise<void>
```

interface InterceptorRequestAllow {
  /**
   * Indicates that the interceptor will allow the buyer's journey to continue.
   */
  behavior: 'allow';

  /**
   * This callback is called when all interceptors finish. We recommend
   * setting errors or reasons for blocking at this stage, so that all the errors in
   * the UI show up at once.
   * @param result InterceptorResult with behavior as either 'allow' or 'block'
   */
  perform?(result: InterceptorResult): void | Promise<void>;
}

InterceptorResult

InterceptorResultAllow | InterceptorResultBlock

InterceptorResultAllow

behavior
Indicates that the buyer was allowed to progress through checkout.
```
"allow"
```

interface InterceptorResultAllow {
  /**
   * Indicates that the buyer was allowed to progress through checkout.
   */
  behavior: 'allow';
}

InterceptorResultBlock

behavior
Indicates that some part of the checkout UI intercepted and prevented the buyer’s progress. The buyer typically needs to take some action to resolve this issue and to move on to the next step.
```
"block"
```

interface InterceptorResultBlock {
  /**
   * Indicates that some part of the checkout UI intercepted and prevented
   * the buyer’s progress. The buyer typically needs to take some action
   * to resolve this issue and to move on to the next step.
   */
  behavior: 'block';
}

InterceptorRequestBlock

behavior
Indicates that the interceptor will block the buyer's journey from continuing.
```
"block"
```
reason
The reason for blocking the interceptor request. This value isn't presented to the buyer, so it doesn't need to be localized. The value is used only for Shopify’s own internal debugging and metrics.
```
string
```
errors
Used to pass errors to the checkout UI, outside your extension's UI boundaries.
```
ValidationError[]
```
perform
This callback is called when all interceptors finish. We recommend setting errors or reasons for blocking at this stage, so that all the errors in the UI show up at once.
```
(result: InterceptorResult) => void | Promise<void>
```

interface InterceptorRequestBlock {
  /**
   * Indicates that the interceptor will block the buyer's journey from continuing.
   */
  behavior: 'block';

  /**
   * The reason for blocking the interceptor request. This value isn't presented to
   * the buyer, so it doesn't need to be localized. The value is used only for Shopify’s
   * own internal debugging and metrics.
   */
  reason: string;

  /**
   * Used to pass errors to the checkout UI, outside your extension's UI boundaries.
   */
  errors?: ValidationError[];

  /**
   * This callback is called when all interceptors finish. We recommend
   * setting errors or reasons for blocking at this stage, so that all the errors in
   * the UI show up at once.
   * @param result InterceptorResult with behavior as either 'allow' or 'block'
   */
  perform?(result: InterceptorResult): void | Promise<void>;
}

ValidationError

message
Error message to be displayed to the buyer.
```
string
```
target
The checkout UI field that the error is associated with. Example: `$.cart.deliveryGroups[0].deliveryAddress.countryCode` See the [supported targets](/docs/api/functions/reference/cart-checkout-validation/graphql#supported-targets) for more information.
```
string
```

export interface ValidationError {
  /**
   * Error message to be displayed to the buyer.
   */
  message: string;
  /**
   * The checkout UI field that the error is associated with.
   *
   * Example: `$.cart.deliveryGroups[0].deliveryAddress.countryCode`
   *
   * See the [supported targets](/docs/api/functions/reference/cart-checkout-validation/graphql#supported-targets)
   * for more information.
   */
  target?: string;
}

Was this section helpful?

Anchor to useBuyerJourneyCompleted
useBuyerJourneyCompleted()

Returns true if the buyer completed submitting their order. For example, when viewing the Order status page after submitting payment, the buyer will have completed their order.

Anchor to useBuyerJourneyCompleted-returnsReturns

false | true

UseBuyerJourneyCompletedGeneratedType

Returns true if the buyer completed submitting their order. For example, when viewing the **Order status** page after submitting payment, the buyer will have completed their order.

false | true

false | true

export function useBuyerJourneyCompleted<
  Target extends RenderExtensionTarget = RenderExtensionTarget,
>(): boolean {
  const api = useApi<Target>();

  if ('buyerJourney' in api) {
    return useSubscription(api.buyerJourney.completed);
  }

  throw new ExtensionHasNoMethodError('buyerJourney', api.extension.target);
}

Was this section helpful?

Anchor to useBuyerJourneyIntercept
useBuyerJourneyIntercept(
interceptor
)

Installs a function for intercepting and preventing progress on checkout. To block checkout progress, you must set the block_progress capability in your extension's configuration. If you do, then you're expected to inform the buyer why navigation was blocked, either by passing validation errors to the checkout UI or rendering the errors in your extension.

Anchor to useBuyerJourneyIntercept-parametersParameters

Anchor to interceptor interceptor required

Anchor to useBuyerJourneyIntercept-returnsReturns
void

UseBuyerJourneyInterceptGeneratedType

Installs a function for intercepting and preventing progress on checkout. To block checkout progress, you must set the [block_progress](/docs/api/checkout-ui-extensions/configuration#block-progress) capability in your extension's configuration. If you do, then you're expected to inform the buyer why navigation was blocked, either by passing validation errors to the checkout UI or rendering the errors in your extension.

interceptor
```
Interceptor
```

void

void

export function useBuyerJourneyIntercept<
  Target extends RenderExtensionTarget = RenderExtensionTarget,
>(interceptor: Interceptor): void {
  const api = useApi<Target>();

  if (!('buyerJourney' in api)) {
    throw new ExtensionHasNoMethodError('buyerJourney', api.extension.target);
  }

  const interceptorRef = useRef(interceptor);
  interceptorRef.current = interceptor;

  return useEffect(() => {
    const teardownPromise = api.buyerJourney.intercept((interceptorProps) =>
      interceptorRef.current(interceptorProps),
    );

    return () => {
      teardownPromise.then((teardown) => teardown()).catch(() => {});
    };
  }, [api.buyerJourney]);
}

Interceptor

(
  interceptorProps: InterceptorProps,
) => InterceptorRequest | Promise<InterceptorRequest>

InterceptorProps

canBlockProgress
Whether the interceptor has the capability to block a buyer's progress through checkout. This ability might be granted by a merchant in differing checkout contexts.
```
boolean
```

export interface InterceptorProps {
  /**
   * Whether the interceptor has the capability to block a buyer's progress through
   * checkout. This ability might be granted by a merchant in differing checkout contexts.
   */
  canBlockProgress: boolean;
}

InterceptorRequest

InterceptorRequestAllow | InterceptorRequestBlock

InterceptorRequestAllow

behavior
Indicates that the interceptor will allow the buyer's journey to continue.
```
"allow"
```
perform
This callback is called when all interceptors finish. We recommend setting errors or reasons for blocking at this stage, so that all the errors in the UI show up at once.
```
(result: InterceptorResult) => void | Promise<void>
```

interface InterceptorRequestAllow {
  /**
   * Indicates that the interceptor will allow the buyer's journey to continue.
   */
  behavior: 'allow';

  /**
   * This callback is called when all interceptors finish. We recommend
   * setting errors or reasons for blocking at this stage, so that all the errors in
   * the UI show up at once.
   * @param result InterceptorResult with behavior as either 'allow' or 'block'
   */
  perform?(result: InterceptorResult): void | Promise<void>;
}

InterceptorResult

InterceptorResultAllow | InterceptorResultBlock

InterceptorResultAllow

behavior
Indicates that the buyer was allowed to progress through checkout.
```
"allow"
```

interface InterceptorResultAllow {
  /**
   * Indicates that the buyer was allowed to progress through checkout.
   */
  behavior: 'allow';
}

InterceptorResultBlock

behavior
Indicates that some part of the checkout UI intercepted and prevented the buyer’s progress. The buyer typically needs to take some action to resolve this issue and to move on to the next step.
```
"block"
```

interface InterceptorResultBlock {
  /**
   * Indicates that some part of the checkout UI intercepted and prevented
   * the buyer’s progress. The buyer typically needs to take some action
   * to resolve this issue and to move on to the next step.
   */
  behavior: 'block';
}

InterceptorRequestBlock

behavior
Indicates that the interceptor will block the buyer's journey from continuing.
```
"block"
```
reason
The reason for blocking the interceptor request. This value isn't presented to the buyer, so it doesn't need to be localized. The value is used only for Shopify’s own internal debugging and metrics.
```
string
```
errors
Used to pass errors to the checkout UI, outside your extension's UI boundaries.
```
ValidationError[]
```
perform
This callback is called when all interceptors finish. We recommend setting errors or reasons for blocking at this stage, so that all the errors in the UI show up at once.
```
(result: InterceptorResult) => void | Promise<void>
```

interface InterceptorRequestBlock {
  /**
   * Indicates that the interceptor will block the buyer's journey from continuing.
   */
  behavior: 'block';

  /**
   * The reason for blocking the interceptor request. This value isn't presented to
   * the buyer, so it doesn't need to be localized. The value is used only for Shopify’s
   * own internal debugging and metrics.
   */
  reason: string;

  /**
   * Used to pass errors to the checkout UI, outside your extension's UI boundaries.
   */
  errors?: ValidationError[];

  /**
   * This callback is called when all interceptors finish. We recommend
   * setting errors or reasons for blocking at this stage, so that all the errors in
   * the UI show up at once.
   * @param result InterceptorResult with behavior as either 'allow' or 'block'
   */
  perform?(result: InterceptorResult): void | Promise<void>;
}

ValidationError

message
Error message to be displayed to the buyer.
```
string
```
target
The checkout UI field that the error is associated with. Example: `$.cart.deliveryGroups[0].deliveryAddress.countryCode` See the [supported targets](/docs/api/functions/reference/cart-checkout-validation/graphql#supported-targets) for more information.
```
string
```

export interface ValidationError {
  /**
   * Error message to be displayed to the buyer.
   */
  message: string;
  /**
   * The checkout UI field that the error is associated with.
   *
   * Example: `$.cart.deliveryGroups[0].deliveryAddress.countryCode`
   *
   * See the [supported targets](/docs/api/functions/reference/cart-checkout-validation/graphql#supported-targets)
   * for more information.
   */
  target?: string;
}

Was this section helpful?

Block progress and show error for a checkout UI field

import {

reactExtension,

useBuyerJourneyIntercept,

useShippingAddress,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.delivery-address.render-before',

() => <Extension />,

);

function Extension() {

const address = useShippingAddress();

useBuyerJourneyIntercept(

({canBlockProgress}) => {

return canBlockProgress &&

address?.countryCode &&

address.countryCode !== 'CA'

? {

behavior: 'block',

reason: 'Invalid shipping country',

errors: [

{

message:

'Sorry, we can only ship to Canada',

// Show an error underneath the country code field

target:

'$.cart.deliveryGroups[0].deliveryAddress.countryCode',

{

// In addition, show an error at the page level

message:

'Please use a different address.',

}

: {

behavior: 'allow',

};

);

return null;

}

examples

Block progress and show error for a checkout UI field

description

Intercept and prevent a buyer's progress through checkout while targeting a specific checkout UI field. See the [validation tutorial](/docs/apps/checkout/validation) for more examples and best practices.

React

import {
  reactExtension,
  useBuyerJourneyIntercept,
  useShippingAddress,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.delivery-address.render-before',
  () => <Extension />,
);

function Extension() {
  const address = useShippingAddress();

  useBuyerJourneyIntercept(
    ({canBlockProgress}) => {
      return canBlockProgress &&
        address?.countryCode &&
        address.countryCode !== 'CA'
        ? {
            behavior: 'block',
            reason: 'Invalid shipping country',
            errors: [
              {
                message:
                  'Sorry, we can only ship to Canada',
                // Show an error underneath the country code field
                target:
                  '$.cart.deliveryGroups[0].deliveryAddress.countryCode',
              },
              {
                // In addition, show an error at the page level
                message:
                  'Please use a different address.',
              },
            ],
          }
        : {
            behavior: 'allow',
          };
    },
  );

  return null;
}

JavaScript

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

export default extension(
  'purchase.checkout.delivery-address.render-before',
  (root, {buyerJourney, shippingAddress}) => {
    let address = shippingAddress?.current;
    shippingAddress?.subscribe((newAddress) => {
      address = newAddress;
    });

    buyerJourney.intercept(
      ({canBlockProgress}) => {
        return canBlockProgress &&
          address?.countryCode &&
          address.countryCode !== 'CA'
          ? {
              behavior: 'block',
              reason: 'Invalid shipping country',
              errors: [
                {
                  message:
                    'Sorry, we can only ship to Canada',
                  // Show an error underneath the country code field
                  target:
                    '$.cart.deliveryGroups[0].deliveryAddress.countryCode',
                },
                {
                  // In addition, show an error at the page level
                  message:
                    'Please use a different address.',
                },
              ],
            }
          : {
              behavior: 'allow',
            };
      },
    );
  },
);

Anchor to examplesExamples

In addition to targeting checkout UI fields, you can also pass errors to the page level or render the error in your extension.

Anchor to example-block-progress-and-show-error-at-page-levelBlock progress and show error at page level

Intercept and prevent a buyer's progress through checkout while displaying an error message at the page level. See the validation tutorial for more examples and best practices.

Anchor to example-block-progress-and-show-error-in-your-extensionBlock progress and show error in your extension

Intercept and prevent a buyer's progress through checkout while displaying an error message in your extension. See the validation tutorial for more examples and best practices.

Was this section helpful?

Block progress and show error at page level

import {

reactExtension,

useBuyerJourneyIntercept,

useShippingAddress,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.delivery-address.render-before',

() => <Extension />,

);

function Extension() {

const address = useShippingAddress();

useBuyerJourneyIntercept(

({canBlockProgress}) => {

return canBlockProgress &&

address?.countryCode &&

address.countryCode !== 'CA'

? {

behavior: 'block',

reason: 'Invalid shipping country',

errors: [

{

// An error without a `target` property is shown at page level

message:

'Sorry, we can only ship to Canada',

}

: {

behavior: 'allow',

};

);

return null;

}

examples

Block progress and show error at page level

description

Intercept and prevent a buyer's progress through checkout while displaying an error message at the page level. See the [validation tutorial](/docs/apps/checkout/validation) for more examples and best practices.

React

import {
  reactExtension,
  useBuyerJourneyIntercept,
  useShippingAddress,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.delivery-address.render-before',
  () => <Extension />,
);

function Extension() {
  const address = useShippingAddress();

  useBuyerJourneyIntercept(
    ({canBlockProgress}) => {
      return canBlockProgress &&
        address?.countryCode &&
        address.countryCode !== 'CA'
        ? {
            behavior: 'block',
            reason: 'Invalid shipping country',
            errors: [
              {
                // An error without a `target` property is shown at page level
                message:
                  'Sorry, we can only ship to Canada',
              },
            ],
          }
        : {
            behavior: 'allow',
          };
    },
  );

  return null;
}

JavaScript

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

export default extension(
  'purchase.checkout.delivery-address.render-before',
  (root, {buyerJourney, shippingAddress}) => {
    let address = shippingAddress?.current;
    shippingAddress?.subscribe((newAddress) => {
      address = newAddress;
    });

    buyerJourney.intercept(
      ({canBlockProgress}) => {
        return canBlockProgress &&
          address?.countryCode &&
          address.countryCode !== 'CA'
          ? {
              behavior: 'block',
              reason: 'Invalid shipping country',
              errors: [
                {
                  // An error without a `target` property is shown at page level
                  message:
                    'Sorry, we can only ship to Canada',
                },
              ],
            }
          : {
              behavior: 'allow',
            };
      },
    );
  },
);

Block progress and show error in your extension

description

Intercept and prevent a buyer's progress through checkout while displaying an error message in your extension. See the [validation tutorial](/docs/apps/checkout/validation) for more examples and best practices.

React

import {useState} from 'react';
import {
  reactExtension,
  Banner,
  useBuyerJourneyIntercept,
  useCartLineTarget,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.cart-line-item.render-after',
  () => <Extension />,
);

function Extension() {
  const [showError, setShowError] =
    useState(false);
  const {quantity} = useCartLineTarget();

  useBuyerJourneyIntercept(
    ({canBlockProgress}) => {
      return canBlockProgress && quantity > 1
        ? {
            behavior: 'block',
            reason: 'limited stock',
            perform: (result) => {
              if (result.behavior === 'block') {
                setShowError(true);
              }
            },
          }
        : {
            behavior: 'allow',
            perform: () => {
              setShowError(false);
            },
          };
    },
  );

  return showError ? (
    <Banner>
      This item has a limit of one per customer.
    </Banner>
  ) : null;
}

JavaScript

import {
  extension,
  Banner,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.cart-line-item.render-after',
  (root, {buyerJourney, target}) => {
    const banner = root.createComponent(Banner);

    let quantity = target.current.quantity;

    target?.subscribe((newTarget) => {
      quantity = newTarget.quantity;
    });

    buyerJourney.intercept(
      ({canBlockProgress}) => {
        return canBlockProgress && quantity > 1
          ? {
              behavior: 'block',
              reason: 'limited stock',
              perform: (result) => {
                if (result.behavior === 'block') {
                  banner.appendChild(
                    'This item has a limit of one per customer.',
                  );
                  root.appendChild(banner);
                }
              },
            }
          : {
              behavior: 'allow',
              perform: () => {
                root.removeChild(banner);
              },
            };
      },
    );
  },
);