Skip to main content

Buyer Journey
API

The API for interacting with the buyer journey.

The base API object provided to purchase extension targets.

required

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

Refer to buyer journey examples for more information.

Was this section helpful?

Anchor to useBuyerJourney
useBuyerJourney()

Returns the buyerJourney details on buyer progression in checkout.

BuyerJourney

activeStep
StatefulRemoteSubscribable< | undefined>

What step of checkout the buyer is currently on.

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.

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.

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.

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.

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.

false | true
Was this section helpful?

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. useBuyerJourneyIntercept() should be called at the top level of the extension, not within an embedded or child component, to avoid errors should the child component get destroyed.

required

Was this section helpful?

Anchor to useBuyerJourneySteps
useBuyerJourneySteps()

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.

[]
Was this section helpful?

Anchor to useBuyerJourneyActiveStep
useBuyerJourneyActiveStep()

Returns the buyer journey step that the buyer is currently on.

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

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