How to Block a User on Clicking "Continue" to Payment Page in Shopify One Page Checkout?

Shopify Plus
, , ,
1

I’m building a Shopify One Page Checkout extension, and I need to block a user from proceeding to the payment page unless certain conditions are met. Specifically, I want to intercept the “Continue” button click, and only allow the user to continue if an API returns a positive value.

Can anyone guide me on how to implement this logic in the checkout flow? I want to ensure that if the API call returns a negative or invalid value, the user cannot proceed to the payment page.

Looking forward to any suggestions or best practices to achieve this!

Thanks in advance for your help!

2

The hook you’re looking for is useBuyerJourneyIntercept from @shopify/ui-extensions-react/checkout. It’s designed exactly for this use case - intercepting step transitions and conditionally blocking progress based on async logic.

Here’s the basic pattern:

import {
 useBuyerJourneyIntercept,
 useExtensionCapability,
} from ""@shopify/ui-extensions-react/checkout"";

const canBlockProgress = useExtensionCapability(""block_progress"");

useBuyerJourneyIntercept(async () => {
 if (!canBlockProgress) {
 return { behavior: ""allow"" };
 }

 const response = await fetch(""https://your-api.com/validate"", { ... });
 const data = await response.json();

 if (data.isValid) {
 return { behavior: ""allow"" };
 }

 return {
 behavior: ""block"",
 reason: ""Validation failed"",
 errors: [
 {
 message: ""You are not eligible to proceed with this order."",
 target: ""$.cart"",
 },
 ],
 };
});

A couple of things worth knowing before you go too far down this path:

First, you need to explicitly enable the block_progress capability in your extension’s shopify.extension.toml:

[extensions.capabilities]
block_progress = true

Without that, canBlockProgress will always be false and you won’t be able to block anything.

Second - and this is a known limitation worth flagging - useBuyerJourneyIntercept doesn’t fire for accelerated checkout methods like Apple Pay, Google Pay, or Shop Pay. If a buyer uses those, the intercept is bypassed entirely. There are open threads about this in the community and it’s a platform-level constraint right now, not something you can work around on the extension side. Worth designing around if your validation is critical.

Also keep the API call as fast as possible. You’re blocking the user’s checkout flow while waiting for the response, so latency matters here.