VerifyHuman Installation Guide

This guide walks you through installing the VerifyHuman Shopify app, obtaining your API key, and enabling verification features on your store.

Prerequisites

Before you begin, make sure you have:

• A Shopify store on any plan (Basic, Shopify, Advanced, or Plus)
• Admin access to your Shopify store
• A VerifyHuman account at app.verifyhuman.io

Step 1: Install the VerifyHuman App

1. Visit the VerifyHuman listing on the Shopify App Store (or use the direct install link provided by VerifyHuman).
2. Click Add app and authorize the requested permissions.
3. The app requires the following Shopify access scopes:
   • read_products / write_products — to detect restricted products via tags and metafields
   • read_customers / write_customers — to store verification status on customer accounts
   • read_orders / write_orders — to associate verification with orders
   • read_themes / write_themes — to set the app URL metafield for widget communication
4. After authorization, you will be redirected to the VerifyHuman dashboard inside your Shopify admin.

Step 2: Create Your VerifyHuman API Key

The API key connects your Shopify store to the VerifyHuman verification service.

1. Go to app.verifyhuman.io and sign in (or create an account).
2. Navigate to Settings > API Keys in your VerifyHuman dashboard.
3. Click Create API Key and select the scopes you need:
   • verify:age — enables age verification (Age Gate)
   • verify:identity — enables identity/KYC verification
   • verify:human — enables bot detection (Human Check)
4. Copy the generated key. It will start with vhk_live_ (production) or vhk_test_ (testing).
5. Return to the VerifyHuman app in your Shopify admin.
6. Go to the Settings page and paste your API key into the VerifyHuman API Key field.
7. Click Save. The key is encrypted and stored securely.

Tip: Use a vhk_test_ key during initial setup so you can test without affecting real customers. Switch to a vhk_live_ key when you are ready to go live.

Step 3: Complete the Onboarding Wizard

If this is your first time setting up the app, the onboarding wizard will guide you through initial configuration:

1. Connect Your Account — Enter or confirm your API key.
2. Choose Your Protection Level — Select the minimum verification level for your store:
   • L1 — Human Check: Bot detection for basic security.
   • L2 — Age Verification: Verify customers meet a minimum age requirement (most popular).
   • L3 — Identity Verification: Full KYC with government ID and selfie matching.
3. Configure Thresholds — Set your age requirement (18+, 21+, or 25+) and optionally set a high-value cart threshold that automatically triggers L3 identity verification.
4. Review & Complete — Confirm your settings, optionally add your privacy policy URL, and finalize setup.

You can adjust all of these settings later from the Settings page.

Step 4: Enable Widgets via Theme App Extension

VerifyHuman uses a Theme App Extension to inject verification widgets into your storefront. No manual code editing is required.

The extension provides four components:

App Embeds work site-wide and are toggled on/off in the theme editor's App Embeds section.

App Blocks are added to specific pages or sections within the theme editor.

For detailed instructions on enabling each widget, see the Theme App Extension Setup guide.

Step 5: Tag Products (If Using Tag-Based Triggers)

If you are using tag-based trigger modes (rather than applying verification to your entire store), you need to tag the relevant products or collections.

For Age Gate (Product Tag mode)

1. Go to Products in your Shopify admin.
2. Open the product that requires age verification.
3. Add the tag age-restricted (or your custom tag configured in the theme editor).
4. Save the product.

For Age Gate (Collection Tag mode)

1. Go to Products > Collections in your Shopify admin.
2. Open the collection that contains age-restricted products.
3. Add the tag age-restricted (or your custom tag).
4. Save the collection.

For Identity Verification (Checkout Guard)

1. Open the product in your Shopify admin.
2. Add the tag vh_requires_idv.
3. Alternatively, set the product metafield verifyhuman.requires_idv to true.
4. Save the product.

When a customer adds a tagged product to their cart, the checkout guard will require identity verification before allowing checkout.

Step 6: Test Your Setup

After installation and configuration:

1. Open your storefront in a private/incognito browser window.
2. Visit a page where verification should trigger.
3. Confirm the verification overlay or widget appears as expected.
4. Complete a test verification to ensure the flow works end to end.

If you used a vhk_test_ API key, verifications will succeed without real document checks. Switch to vhk_live_ for production use.

For detailed testing steps, see Testing Your Setup.

Troubleshooting

Widgets not appearing in the theme editor

• Make sure the Theme App Extension has been deployed. If the VerifyHuman widgets do not appear under App Embeds or App Blocks, contact support to confirm the extension is deployed to your store.
• Identity Verification is an App Block, not an App Embed. It will not appear in the "App embeds" section. Instead, navigate to a page template, click + Add block, and look for it under Apps.

"App URL metafield not set" console warning

This means the verifyhuman.app_url shop metafield has not been configured. Reinstalling the app or saving settings from the dashboard should set this automatically.

Verification not triggering on tagged products

• Confirm the tag is spelled exactly as configured (tags are case-insensitive).
• For age gate, check that Apply Age Gate To is set to "Products with Specific Tag" or "Collections with Specific Tag" rather than "Entire Store."
• Clear your browser cache or use an incognito window to test.

For more help, see Troubleshooting.

Next Steps

• Theme App Extension Setup — Detailed guide for enabling each embed and block
• Age Gate — Configure age verification settings
• Identity Verification — Set up KYC and checkout guards
• Human Verification — Protect forms from bots
• Settings Reference — Complete list of all settings