Dashboard

Getting Started with VerifyHuman for Shopify

This guide walks you through the prerequisites, installation, and initial configuration to get VerifyHuman running on your Shopify store.

Prerequisites

Before installing VerifyHuman, make sure you have:

  1. A Shopify store on any paid plan (Basic, Shopify, Advanced, or Plus).
  2. A VerifyHuman account — sign up at app.verifyhuman.io if you do not have one.
  3. A VerifyHuman API key — create one in your VerifyHuman dashboard under Settings > API Keys.
  4. An Online Store 2.0 theme — required for Theme App Extension support (App Embeds and App Blocks). Most modern Shopify themes support this.

API Key Scopes

When creating your VerifyHuman API key, select the scopes that match the features you plan to use:

Scope Required For
verify:age Age Gate (L2)
verify:identity Identity Verification (L3)
verify:human Human Check / Bot Detection (L1)

Your API key will start with vhk_live_ (production) or vhk_test_ (testing).

Step 1: Install the App

Install VerifyHuman from the Shopify App Store or use a direct install link provided by VerifyHuman.

During installation, Shopify will ask you to approve the following permissions:

Permission Why It Is Needed
Read/write products Detect products that require verification via tags and metafields
Read/write customers Store verification status on customer accounts
Read/write orders Associate verification results with orders
Read/write themes Set the verifyhuman.app_url metafield for widget loading

After approving, you will be redirected to the VerifyHuman dashboard inside your Shopify Admin.

What Happens During Install

The app automatically:

Step 2: Enter Your API Key

Once the app is installed, you need to connect it to your VerifyHuman account:

  1. In your Shopify Admin, open the VerifyHuman app.
  2. If this is your first time, the Onboarding Wizard will appear. Enter your API key on the first step.
  3. If you skipped onboarding or need to update your key later, go to Settings and find the API Configuration section at the top.
  4. Paste your API key and click Save Changes.

Your API key is encrypted before being stored. The dashboard only shows the last 4 characters of a saved key for security.

No API key? Verification features will not work without a valid API key. Visit app.verifyhuman.io to create one.

Step 3: Choose Your Configuration Mode

VerifyHuman offers two configuration modes:

The Onboarding Wizard uses Simple Mode by default. You will choose:

  1. Minimum verification level: L1 (Human Check), L2 (Age Verification), or L3 (Identity Verification).
  2. Age threshold: 18+, 21+, or 25+ (applies when L2 or higher is selected).
  3. High-value cart threshold (optional): Automatically require L3 Identity Verification when the cart total exceeds a dollar amount you set.

Advanced Mode

Switch to Advanced Mode from the Settings page if you need granular control. In Advanced Mode, you independently enable and configure:

Step 4: Enable Widgets in Your Theme

After configuring settings in the dashboard, you need to enable the verification widgets in your Shopify theme:

  1. From your Shopify Admin, go to Online Store > Themes.
  2. Click Customize on your active theme.
  3. In the Theme Editor, click the App embeds icon in the left sidebar (it looks like a puzzle piece with a plus sign, or may be labeled "App embeds").
  4. Toggle on the VerifyHuman widgets you want to use:
    • VerifyHuman - Age Gate: Enables the age verification overlay.
    • VerifyHuman - Human Check: Enables bot detection on forms.
    • VerifyHuman - Checkout ID: Enables pre-checkout identity verification.
  5. Click Save.

For the Identity Verification button (App Block), you add it to a specific section:

  1. Navigate to the page where you want the button (e.g., a product page).
  2. Click + Add block in the section where you want it.
  3. Find Identity Verification under the Apps section.
  4. Configure the block settings (title, button text, colors).
  5. Click Save.

See Theme App Extension Setup for detailed instructions with screenshots and troubleshooting.

Step 5: Tag Restricted Products (Optional)

If you want verification to apply only to specific products rather than your entire store, tag those products:

For Identity Verification (Pre-Checkout Guard)

Add the tag vh_requires_idv to any product that should require identity verification before checkout. You can also set the product metafield verifyhuman.requires_idv to true.

For Age Gate (Product/Collection Scope)

If your Age Gate trigger mode is set to "Products with Specific Tag" or "Collections with Specific Tag", add the tag age-restricted (or your custom tag) to the relevant products or collections.

To tag products:

  1. Go to Products in your Shopify Admin.
  2. Select a product and scroll to the Tags section.
  3. Add the appropriate tag and save.

See Tags and Triggers for the complete tag and metafield reference.

Step 6: Verify Your Setup

Run the built-in diagnostics to confirm everything is working:

  1. Open the VerifyHuman app in your Shopify Admin.
  2. Go to the Settings page.
  3. Scroll to the Diagnostics card.
  4. Confirm all checks show green:
    • App Installed: App is installed and active.
    • API Key Configured: Your VerifyHuman API key is set.
    • Metafield Set: The verifyhuman.app_url metafield is correct. If not, click Repair to fix it automatically.
    • Settings Configured: At least one verification feature is enabled.

Test on Your Storefront

  1. Visit your storefront in an incognito/private browser window.
  2. If the Age Gate is enabled for the entire store, you should see the age verification overlay.
  3. If using product-specific triggering, navigate to a tagged product to see the verification prompt.
  4. Check the Logs page in the dashboard for verification events.

See Testing Your Setup for a detailed testing checklist.

Next Steps