When does useBuyerJourneyIntercept run? (Single-page checkout – every input vs. only Pay now)

Ask & Offer
,
1

Context

I’m building a checkout UI extension that uses useBuyerJourneyIntercept to require acceptance of terms before the buyer can complete the order (block progress when the terms checkbox is unchecked).

What I’m seeing

On single-page checkout, the interceptor seems to run not only when the buyer clicks “Pay now”, but also when they edit other fields (e.g. address). That causes the terms validation to show while they’re still filling the form, which is confusing.

What I need

Clarification on when the interceptor is actually invoked:

  1. Is it only when the buyer tries to submit (e.g. “Pay now” / “Complete order”)?

  2. Or can it also run on other “progress” events (e.g. address/contact validation, step transitions, or field blur)?

The Buyer Journey API docs describe it as “intercepting and preventing progress” and “navigation,” but don’t specify which user actions trigger the interceptor. A short note in the docs or here on when it runs would help extension developers (e.g. to avoid validating terms on address changes and only on final submit).

Workaround so far

I’m using buyerJourney.activeStep and only blocking when the current step is payment or checkout, which improves multi-step checkout but doesn’t fully fix single-page checkout if the interceptor runs on every progress/validation event.

Relevant API

  • useBuyerJourneyIntercept (React) / buyerJourney.intercept() (Preact/vanilla)

  • Extension target: purchase.checkout.actions.render-before

  • Capability: block_progress

2

hii @KedarMalap

useBuyerJourneyIntercept runs whenever Shopify evaluates checkout progress not just on “Pay now.That includes step changes, address updates, and internal re-validations especially on single-page checkout.There’s no final submit only trigger. The correct approach is to check buyerJourney.activeStep` and only return block on the paymentfinal step.

3

Thanks for clarifying that it runs on every progress evaluation, not just Pay now.

One follow-up: I’m on one-page checkout, so buyerJourney.activeStep is always checkout — there’s no separate information / shipping / payment step. If I only block when activeStep === ‘payment’ || activeStep === ‘checkout’, then on one-page I’d still be blocking on every evaluation (address updates, re-validation, etc.), not only when the buyer actually clicks Pay now.

So for one-page checkout, is there any supported way to restrict the block to “final submit” only, or is the intended approach to accept that the interceptor will run on all progress events and we should only block when activeStep === ‘checkout’ and terms aren’t accepted (and live with the fact that the error can show during address/validation too)? Any best practice for this case?