--- title: Buyer Journey description: The API for interacting with the buyer journey. api_version: 2024-07 api_name: checkout-ui-extensions source_url: html: https://shopify.dev/docs/api/checkout-ui-extensions/2024-07/apis/buyer-journey md: https://shopify.dev/docs/api/checkout-ui-extensions/2024-07/apis/buyer-journey.md --- # Buyer JourneyAPI The API for interacting with the buyer journey. ## StandardApi The base API object provided to `purchase` extension targets. * buyerJourney BuyerJourney required Provides details on the buyer's progression through the checkout. Refer to [buyer journey](https://shopify.dev/docs/api/checkout-ui-extensions/apis/buyer-journey#examples) examples for more information. ### BuyerJourney Provides details on the buyer's progression through the checkout. * activeStep What step of checkout the buyer is currently on. ```ts StatefulRemoteSubscribable ``` * 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. ```ts StatefulRemoteSubscribable ``` * 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. ```ts (interceptor: Interceptor) => Promise<() => void> ``` * steps All possible steps a buyer can take to complete the checkout. These steps may vary depending on the type of checkout or the shop's configuration. ```ts StatefulRemoteSubscribable ``` ```ts 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; /** * All possible steps a buyer can take to complete the checkout. These steps may vary depending on the type of checkout or the shop's configuration. */ steps: StatefulRemoteSubscribable; /** * What step of checkout the buyer is currently on. */ activeStep: StatefulRemoteSubscribable; } ``` ### BuyerJourneyStepReference What step of checkout the buyer is currently on. * handle The handle that uniquely identifies the buyer journey step. ```ts BuyerJourneyStepHandle ``` ```ts interface BuyerJourneyStepReference { /** * The handle that uniquely identifies the buyer journey step. */ handle: BuyerJourneyStepHandle; } ``` ### BuyerJourneyStepHandle \| handle | Description | |---|---| | \`cart\` | The cart page. | | \`checkout\` | A one-page checkout, including Shop Pay. | | \`information\` | The contact information step of a three-page checkout. | | \`shipping\` | The shipping step of a three-page checkout. | | \`payment\` | The payment step of a three-page checkout. | | \`review\` | The step after payment where the buyer confirms the purchase. Not all shops are configured to have a review step. | | \`thank-you\` | The page displayed after the purchase, thanking the buyer. | | \`unknown\` | An unknown step in the buyer journey. | ```ts 'cart' | 'checkout' | 'information' | 'shipping' | 'payment' | 'review' | 'thank-you' | 'unknown' ``` ### 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 ```ts InterceptorProps ``` InterceptorRequest | Promise\ ```ts InterceptorRequest | Promise ``` ```ts export type Interceptor = ( interceptorProps: InterceptorProps, ) => InterceptorRequest | Promise; ``` ### 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 ``` ```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; } ``` ### 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" ``` * 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 ``` * 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 ``` ```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; } ``` ### 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; } ``` ### BuyerJourneyStep * disabled The disabled state of the buyer journey step. This value will be true if the buyer has not reached the step yet. For example, if the buyer has not reached the \`shipping\` step yet, \`shipping\` would be disabled. ```ts boolean ``` * handle The handle that uniquely identifies the buyer journey step. ```ts BuyerJourneyStepHandle ``` * label The localized label of the buyer journey step. ```ts string ``` * to The url of the buyer journey step. This property leverages the \`shopify:\` protocol E.g. \`shopify:cart\` or \`shopify:checkout/information\`. ```ts string ``` ```ts export interface BuyerJourneyStep { /** * The handle that uniquely identifies the buyer journey step. */ handle: BuyerJourneyStepHandle; /** * The localized label of the buyer journey step. */ label: string; /** * The url of the buyer journey step. This property leverages the `shopify:` protocol * E.g. `shopify:cart` or `shopify:checkout/information`. */ to: string; /** * The disabled state of the buyer journey step. This value will be true if the buyer has not reached the step yet. * * For example, if the buyer has not reached the `shipping` step yet, `shipping` would be disabled. */ disabled: boolean; } ``` ## use​Buyer​Journey() Returns the buyerJourney details on buyer progression in checkout. ### Returns * BuyerJourney ### BuyerJourney * activeStep StatefulRemoteSubscribable\ What step of checkout the buyer is currently on. * completed StatefulRemoteSubscribable\ 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. * intercept (interceptor: 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](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress) capability in your extension's configuration. * steps StatefulRemoteSubscribable\ All possible steps a buyer can take to complete the checkout. These steps may vary depending on the type of checkout or the shop's configuration. ### BuyerJourney Provides details on the buyer's progression through the checkout. * activeStep What step of checkout the buyer is currently on. ```ts StatefulRemoteSubscribable ``` * 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. ```ts StatefulRemoteSubscribable ``` * 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. ```ts (interceptor: Interceptor) => Promise<() => void> ``` * steps All possible steps a buyer can take to complete the checkout. These steps may vary depending on the type of checkout or the shop's configuration. ```ts StatefulRemoteSubscribable ``` ```ts 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; /** * All possible steps a buyer can take to complete the checkout. These steps may vary depending on the type of checkout or the shop's configuration. */ steps: StatefulRemoteSubscribable; /** * What step of checkout the buyer is currently on. */ activeStep: StatefulRemoteSubscribable; } ``` ### BuyerJourneyStepReference What step of checkout the buyer is currently on. * handle The handle that uniquely identifies the buyer journey step. ```ts BuyerJourneyStepHandle ``` ```ts interface BuyerJourneyStepReference { /** * The handle that uniquely identifies the buyer journey step. */ handle: BuyerJourneyStepHandle; } ``` ### BuyerJourneyStepHandle \| handle | Description | |---|---| | \`cart\` | The cart page. | | \`checkout\` | A one-page checkout, including Shop Pay. | | \`information\` | The contact information step of a three-page checkout. | | \`shipping\` | The shipping step of a three-page checkout. | | \`payment\` | The payment step of a three-page checkout. | | \`review\` | The step after payment where the buyer confirms the purchase. Not all shops are configured to have a review step. | | \`thank-you\` | The page displayed after the purchase, thanking the buyer. | | \`unknown\` | An unknown step in the buyer journey. | ```ts 'cart' | 'checkout' | 'information' | 'shipping' | 'payment' | 'review' | 'thank-you' | 'unknown' ``` ### 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 ```ts InterceptorProps ``` InterceptorRequest | Promise\ ```ts InterceptorRequest | Promise ``` ```ts export type Interceptor = ( interceptorProps: InterceptorProps, ) => InterceptorRequest | Promise; ``` ### 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 ``` ```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; } ``` ### 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" ``` * 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 ``` * 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 ``` ```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; } ``` ### 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; } ``` ### BuyerJourneyStep * disabled The disabled state of the buyer journey step. This value will be true if the buyer has not reached the step yet. For example, if the buyer has not reached the \`shipping\` step yet, \`shipping\` would be disabled. ```ts boolean ``` * handle The handle that uniquely identifies the buyer journey step. ```ts BuyerJourneyStepHandle ``` * label The localized label of the buyer journey step. ```ts string ``` * to The url of the buyer journey step. This property leverages the \`shopify:\` protocol E.g. \`shopify:cart\` or \`shopify:checkout/information\`. ```ts string ``` ```ts export interface BuyerJourneyStep { /** * The handle that uniquely identifies the buyer journey step. */ handle: BuyerJourneyStepHandle; /** * The localized label of the buyer journey step. */ label: string; /** * The url of the buyer journey step. This property leverages the `shopify:` protocol * E.g. `shopify:cart` or `shopify:checkout/information`. */ to: string; /** * The disabled state of the buyer journey step. This value will be true if the buyer has not reached the step yet. * * For example, if the buyer has not reached the `shipping` step yet, `shipping` would be disabled. */ disabled: boolean; } ``` ## use​Buyer​Journey​Completed() 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. ### Returns * false | true ## use​Buyer​Journey​Intercept([interceptor](#usebuyerjourneyintercept-propertydetail-interceptor)​) 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. ### 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. * interceptorProps ```ts InterceptorProps ``` InterceptorRequest | Promise\ ```ts InterceptorRequest | Promise ``` ```ts export type Interceptor = ( interceptorProps: InterceptorProps, ) => InterceptorRequest | Promise; ``` ### 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 ``` ```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; } ``` ### 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" ``` * 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 ``` * 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 ``` ```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; } ``` ### 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; } ``` ## use​Buyer​Journey​Steps() Returns all possible steps a buyer can take to complete the checkout. These steps may vary depending on the type of checkout or the shop's configuration. ### Returns * BuyerJourneyStep\[] ### BuyerJourneyStep * disabled The disabled state of the buyer journey step. This value will be true if the buyer has not reached the step yet. For example, if the buyer has not reached the \`shipping\` step yet, \`shipping\` would be disabled. ```ts boolean ``` * handle The handle that uniquely identifies the buyer journey step. ```ts BuyerJourneyStepHandle ``` * label The localized label of the buyer journey step. ```ts string ``` * to The url of the buyer journey step. This property leverages the \`shopify:\` protocol E.g. \`shopify:cart\` or \`shopify:checkout/information\`. ```ts string ``` ```ts export interface BuyerJourneyStep { /** * The handle that uniquely identifies the buyer journey step. */ handle: BuyerJourneyStepHandle; /** * The localized label of the buyer journey step. */ label: string; /** * The url of the buyer journey step. This property leverages the `shopify:` protocol * E.g. `shopify:cart` or `shopify:checkout/information`. */ to: string; /** * The disabled state of the buyer journey step. This value will be true if the buyer has not reached the step yet. * * For example, if the buyer has not reached the `shipping` step yet, `shipping` would be disabled. */ disabled: boolean; } ``` ### BuyerJourneyStepHandle \| handle | Description | |---|---| | \`cart\` | The cart page. | | \`checkout\` | A one-page checkout, including Shop Pay. | | \`information\` | The contact information step of a three-page checkout. | | \`shipping\` | The shipping step of a three-page checkout. | | \`payment\` | The payment step of a three-page checkout. | | \`review\` | The step after payment where the buyer confirms the purchase. Not all shops are configured to have a review step. | | \`thank-you\` | The page displayed after the purchase, thanking the buyer. | | \`unknown\` | An unknown step in the buyer journey. | ```ts 'cart' | 'checkout' | 'information' | 'shipping' | 'payment' | 'review' | 'thank-you' | 'unknown' ``` ## use​Buyer​Journey​Active​Step() Returns the buyer journey step that the buyer is currently on. ### Returns * BuyerJourneyStep | undefined ### BuyerJourneyStep * disabled The disabled state of the buyer journey step. This value will be true if the buyer has not reached the step yet. For example, if the buyer has not reached the \`shipping\` step yet, \`shipping\` would be disabled. ```ts boolean ``` * handle The handle that uniquely identifies the buyer journey step. ```ts BuyerJourneyStepHandle ``` * label The localized label of the buyer journey step. ```ts string ``` * to The url of the buyer journey step. This property leverages the \`shopify:\` protocol E.g. \`shopify:cart\` or \`shopify:checkout/information\`. ```ts string ``` ```ts export interface BuyerJourneyStep { /** * The handle that uniquely identifies the buyer journey step. */ handle: BuyerJourneyStepHandle; /** * The localized label of the buyer journey step. */ label: string; /** * The url of the buyer journey step. This property leverages the `shopify:` protocol * E.g. `shopify:cart` or `shopify:checkout/information`. */ to: string; /** * The disabled state of the buyer journey step. This value will be true if the buyer has not reached the step yet. * * For example, if the buyer has not reached the `shipping` step yet, `shipping` would be disabled. */ disabled: boolean; } ``` ### BuyerJourneyStepHandle \| handle | Description | |---|---| | \`cart\` | The cart page. | | \`checkout\` | A one-page checkout, including Shop Pay. | | \`information\` | The contact information step of a three-page checkout. | | \`shipping\` | The shipping step of a three-page checkout. | | \`payment\` | The payment step of a three-page checkout. | | \`review\` | The step after payment where the buyer confirms the purchase. Not all shops are configured to have a review step. | | \`thank-you\` | The page displayed after the purchase, thanking the buyer. | | \`unknown\` | An unknown step in the buyer journey. | ```ts 'cart' | 'checkout' | 'information' | 'shipping' | 'payment' | 'review' | 'thank-you' | 'unknown' ``` ### 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', () => , ); 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 ```js 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', }; }, ); }, ); ``` ## 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', () => , ); 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 ```js 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 ```jsx 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', () => , ); 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 ? ( This item has a limit of one per customer. ) : null; } ``` ##### JavaScript ```js 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); }, }; }, ); }, ); ``` ## 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/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/targets) [ReferenceTargets](https://shopify.dev/docs/api/checkout-ui-extensions/targets) [![](https://shopify.dev/images/icons/32/apps.png)![](https://shopify.dev/images/icons/32/apps-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/components) [ReferenceComponents](https://shopify.dev/docs/api/checkout-ui-extensions/components) [![](https://shopify.dev/images/icons/32/gear.png)![](https://shopify.dev/images/icons/32/gear-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) [ReferenceConfiguration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) [![](https://shopify.dev/images/icons/32/tutorial.png)![](https://shopify.dev/images/icons/32/tutorial-dark.png)](https://shopify.dev/apps/checkout) [LearnTutorials](https://shopify.dev/apps/checkout)