---
title: useBuyerJourneyIntercept
description: |-
  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.
api_version: 2023-07
api_name: checkout-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/checkout-ui-extensions/2023-07/react-hooks/buyer-journey/usebuyerjourneyintercept
  md: https://shopify.dev/docs/api/checkout-ui-extensions/2023-07/react-hooks/buyer-journey/usebuyerjourneyintercept.md
---

# use​Buyer​Journey​Intercepthook

Installs a function for intercepting and preventing progress on checkout.

To block checkout progress, you must set the [block\_progress](https://shopify.dev/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.

## use​Buyer​Journey​Intercept([interceptor](#-propertydetail-interceptor)​)

### Parameters

* interceptor

  Interceptor

  required

### Returnsvoid

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

```ts
(
  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.

  ```ts
  boolean
  ```

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

```ts
InterceptorRequestAllow | InterceptorRequestBlock
```

### InterceptorRequestAllow

* behavior

  Indicates that the interceptor will allow the buyer's journey to continue.

  ```ts
  "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.

  ```ts
  (result: InterceptorResult) => void | Promise<void>
  ```

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

```ts
InterceptorResultAllow | InterceptorResultBlock
```

### InterceptorResultAllow

* behavior

  Indicates that the buyer was allowed to progress through checkout.

  ```ts
  "allow"
  ```

```ts
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.

  ```ts
  "block"
  ```

```ts
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.

  ```ts
  "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.

  ```ts
  string
  ```

* errors

  Used to pass errors to the checkout UI, outside your extension's UI boundaries.

  ```ts
  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.

  ```ts
  (result: InterceptorResult) => void | Promise<void>
  ```

```ts
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.

  ```ts
  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.

  ```ts
  string
  ```

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

## InterceptorRequestBlock

Block the buyer from proceeding further in the checkout

* behavior

  "block"

  required

  Indicates that the interceptor will block the buyer's journey from continuing.

* reason

  string

  required

  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.

* errors

  ValidationError\[]

  Used to pass errors to the checkout UI, outside your extension's UI boundaries.

* perform

  (result: InterceptorResult) => void | Promise\<void>

  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.

### ValidationError

* message

  Error message to be displayed to the buyer.

  ```ts
  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.

  ```ts
  string
  ```

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

### InterceptorResult

```ts
InterceptorResultAllow | InterceptorResultBlock
```

### InterceptorResultAllow

* behavior

  Indicates that the buyer was allowed to progress through checkout.

  ```ts
  "allow"
  ```

```ts
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.

  ```ts
  "block"
  ```

```ts
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';
}
```

## InterceptorRequestAllow

Allow the buyer to proceed further in the checkout

* behavior

  "allow"

  required

  Indicates that the interceptor will allow the buyer's journey to continue.

* perform

  (result: InterceptorResult) => void | Promise\<void>

  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.

### InterceptorResult

```ts
InterceptorResultAllow | InterceptorResultBlock
```

### InterceptorResultAllow

* behavior

  Indicates that the buyer was allowed to progress through checkout.

  ```ts
  "allow"
  ```

```ts
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.

  ```ts
  "block"
  ```

```ts
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';
}
```

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

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

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

Block 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](https://shopify.dev/docs/apps/checkout/validation) for more examples and best practices.

Block 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](https://shopify.dev/docs/apps/checkout/validation) for more examples and best practices.

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

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

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

  ```jsx
  import {useState} from 'react';
  import {
    reactExtension,
    Banner,
    useBuyerJourneyIntercept,
    useTarget,
  } 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} = useTarget();

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

## Related

[![](https://shopify.dev/images/icons/32/tutorial.png)![](https://shopify.dev/images/icons/32/tutorial-dark.png)](https://shopify.dev/docs/apps/checkout/validation/fields)

[TutorialValidating fields at checkout](https://shopify.dev/docs/apps/checkout/validation/fields)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi)

[APIsStandardApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/checkoutapi)

[APIsCheckoutApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/checkoutapi)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/orderstatusapi)

[APIsOrderStatusApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/orderstatusapi)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cartlineitemapi)

[APIsCartLineItemApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cartlineitemapi)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuppointlistapi)

[APIsPickupPointListApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuppointlistapi)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuplocationlistapi)

[APIsPickupLocationListApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuplocationlistapi)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/shippingoptionitemapi)

[APIsShippingOptionItemApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/shippingoptionitemapi)

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/apis/extensiontargets)

[APIsExtensionTargets](https://shopify.dev/docs/api/checkout-ui-extensions/apis/extensiontargets)