CAPTCHA

Shopify uses hCaptcha to help prevent spam through customer, contact, and blog comment forms.

Initially, hCaptcha analyzes website visitor behavior to provide a score indicating the likelihood of the visitor being a bot, without requiring the visitor to solve an interactive challenge.

If the assessment result is suspicious enough, or if too many requests are made within a short period of time, then the visitor is redirected to the /challenge page to perform an interactive challenge for further assessment.

Merchants are able to disable hCaptcha functionality on the Online Store > Preferences page in the Shopify admin.

How CAPTCHA is included in themes

Anchor link to section titled "How CAPTCHA is included in themes"

The necessary code for the CAPTCHA functionality is included through the content_for_header object. This means that if a merchant has CAPTCHA enabled, but the content_for_header object isn't present, then the CAPTCHA functionality won't be present.

The CAPTCHA functionality is initialized based on the presence of customer, contact, and blog comment forms, and by default is triggered when the forms are interacted with. For example, the functionality is triggered when a user clicks a text field of an associated form.

These forms are identified based on the action attribute of the form, as well as specific input attributes:

Form type Form action attribute Input attributes (included on a single input)

Customer

Form type	Form `action` attribute	Input attributes (included on a single input)
Customer	Contains `/account`	`name="form_type"` One of the following, depending on the form: `value="customer_login"` `value="create_customer"` `value="recover_customer_password"`
Contact	Contains `/contact`	`name="form_type"` One of the following, depending on the form: `value="contact"` `value="customer"`
Blog	Contains `/blogs`	`name="form_type"` `value="new_comment"`

Contains /account

name="form_type"

One of the following, depending on the form:

value="customer_login"
value="create_customer"
value="recover_customer_password"

Contact

Contains /contact

name="form_type"

One of the following, depending on the form:

value="contact"
value="customer"

Blog

Contains /blogs

name="form_type"
value="new_comment"

In addition to triggering the CAPTCHA functionality on user interaction, a CAPTCHA logo is added to the bottom right corner of the page to notify visitors of the behavior analysis. You can opt to show a text disclaimer with the form instead.

Show a text disclaimer

Anchor link to section titled "Show a text disclaimer"

If CAPTCHA is enabled and CAPTCHA has loaded, then the CAPTCHA logo appears in the bottom right corner of any associated pages. You can choose to show a text disclaimer with the form, rather than this logo.

To do this, you need to include the following code within any forms you wish to change this for:

Advanced: Forcing CAPTCHA wire up to a form

Anchor link to section titled "Advanced: Forcing CAPTCHA wire up to a form"

In some scenarios, it might be necessary to force CAPTCHA wire up to a form. For example, the form might be indirectly populated and submitted, so the default behavior of wiring CAPTCHA on user interaction never happens. In these cases, you have the following options:

Wire up using a data attribute

Anchor link to section titled "Wire up using a data attribute"

Adding the data-shopify-captcha attribute with a value of true causes CAPTCHA to wire up to the form immediately when the page loads.

Wire up using JavaScript

Anchor link to section titled "Wire up using JavaScript"

Alternatively, CAPTCHA can be wired up to a form using JavaScript. window.Shopify.captcha.protect should be invoked with the form that you want to wire up as the first argument, and with an optional callback function as the second argument. If provided, the callback is invoked after CAPTCHA is ready.

This is primarily useful in cases where you programmatically manipulate and submit the form in response to other user action.

Verifying that hCaptcha is wired up

Anchor link to section titled "Verifying that hCaptcha is wired up"

You can verify that hCaptcha is correctly wired to your form by using your browser's network dev tools while the form is being submitted.

Open dev tools on the Network tab.
Fill in and submit the form.
In the browser's dev tools, inspect the payload of the POST request to the server.
Ensure that the h-captcha-response field is present and contains data.

Troubleshooting

Anchor link to section titled "Troubleshooting"

Ensure that your theme includes Liquid's content_for_header object in layouts that contain forms that require hCaptcha. Ensure that no code modifies or changes this object.
If you want your form to be automatically wired up, ensure that its markup is correct, with the requisite action attribute and corresponding form_type child input. For more information, refer to how CAPTCHA is included in themes.
By default, hCaptcha is initialized on the DOMContentLoaded event, but is only wired up when the user interacts with the form. If you're building or submitting forms programmatically or adding them to the DOM after the DOMContentLoaded event has been emitted, then you might need to use window.Shopify.captcha.protect to ensure that CAPTCHA executes correctly.
Some third-party applications may block hCaptcha resources, or otherwise manipulate the DOM in ways that cause hCaptcha to not wire up correctly. Such apps could be focused on improving page load metrics or managing GDPR consent. Consider temporarily disabling such apps while you debug. Often the apps have ignore lists that enable you to fix the issue after it's identified.