Tags and Triggers

VerifyHuman uses product tags, product metafields, collection tags, customer metafields, cart attributes, and cart total thresholds to determine when and what level of verification is required. This page documents every trigger mechanism and how verification levels are computed.

Verification Levels Overview

VerifyHuman defines three assurance levels:

Higher levels provide stronger assurance. A customer verified at L3 also satisfies L2 and L1 requirements.

Product Tags

Product tags are the simplest way to mark products as requiring verification. Tags are checked by both the storefront Liquid templates (theme app extension) and the server-side cart validation function.

Identity Verification Tags

Age Verification Tags

Age Gate Tags (Theme Extension)

The Age Gate embed supports a configurable product tag (default: age-restricted) for triggering the age gate overlay when the trigger mode is set to "Products with Specific Tag." This tag is separate from the checkout validation tags above and only controls whether the storefront overlay appears.

How to Add Tags to Products

1. Go to Products in your Shopify admin.
2. Select the product you want to restrict.
3. In the Tags field, add the appropriate tag (e.g., vh_requires_idv).
4. Click Save.

You can also bulk-tag products using Shopify's bulk editor or CSV import.

Product Metafields

Metafields provide a structured alternative to tags for marking products as restricted.

verifyhuman.requires_idv

• Namespace: verifyhuman
• Key: requires_idv
• Type: Single-line text
• Accepted values: true, 1, yes (all treated as truthy; anything else is falsy)
• Effect: Same as the vh_requires_idv tag — requires identity verification

This metafield is checked by:

• The cart checkout validation function (server-side, at checkout)
• The identity-checkout Liquid embed (storefront, on the cart page)
• The restricted-detection service (server-side utility)

verifyhuman.required_level

• Namespace: verifyhuman
• Key: required_level
• Type: Single-line text
• Accepted values: 1, 2, 3
• Effect: Overrides any tag-based detection and sets the exact verification level required for the product

This metafield takes precedence over tags. For example, if a product has the vh_requires_idv tag (normally L3) but its required_level metafield is set to 2, only L2 (age verification) is required.

How to Set Product Metafields

1. Go to Products in your Shopify admin.
2. Select the product.
3. Scroll down to Metafields.
4. Add a metafield with namespace verifyhuman and key requires_idv, value true.
5. Click Save.

You may need to define the metafield definition first under Settings > Custom data > Products.

Collection Metafields

Collections can also be marked as restricted using metafields.

verifyhuman.requires_idv

• Namespace: verifyhuman
• Key: requires_idv
• Type: Single-line text
• Accepted values: true, 1, yes
• Effect: All products in the collection are treated as requiring identity verification

This is checked by the server-side restricted-detection service. Note that collection metafield detection is only available when the detection mode includes metafield checks (both or metafields_only).

Customer Metafields

Customer metafields store verification results. These are written by the server (via the Shopify Admin API) after a successful verification and are considered trusted because they cannot be modified by the customer.

How Customer Verification Is Checked

The cart checkout validation function reads these metafields at checkout time:

1. If identity_verified is not true, the customer is treated as unverified.
2. If identity_expires_at is in the past, the verification is treated as expired.
3. The assurance_level is compared against the required level for cart items.
4. For L2 requirements, age_result is parsed (e.g., over_21) and compared against the store's age threshold.

Shop Metafields

Shop-level metafields store global configuration that the cart validation function reads at checkout. These are written by the app when you save settings in the dashboard.

Cart Attributes

For guest checkout (when allowGuestCheckout is enabled), verification tokens are stored as cart attributes since there is no customer account to write metafields to.

The cart validation function performs basic token validation (format and expiration check) but this is not cryptographically verified and provides defense-in-depth only. For compliance-grade verification, require customer accounts.

Cart Total Threshold

In both Simple and Advanced modes, you can configure a High-Value Cart Threshold that automatically upgrades the required verification level to L3 (Identity) when the cart total exceeds a specified dollar amount.

Example: If the threshold is set to $500 and a customer's cart totals $600, identity verification (L3) is required even if none of the individual products have restriction tags or metafields.

Configure this in Dashboard > Settings > Verification Mode > High-Value Cart Threshold.

Level Computation Logic

Simple Mode

In Simple Mode, the system uses a straightforward approach:

1. Start with the store's Minimum Required Level (default: L2).
2. Check each product in the cart for tags (vh_requires_idv, vh_requires_age) or metafields (verifyhuman.requires_idv, verifyhuman.required_level).
3. The required_level product metafield overrides tag-based detection.
4. For products with vh_requires_idv tags or requires_idv metafields, the required level is the store's minimum required level.
5. For products with vh_requires_age tags, L2 is required.
6. If the cart total exceeds the identity cart threshold, upgrade to L3.
7. The highest required level across all cart items is enforced.

Advanced Mode

In Advanced Mode, each verification type is controlled independently:

1. Identity (L3): Required if identityEnabled is true and the cart contains restricted items (tagged or metafield-marked).
2. Age (L2): Required if agegateEnabled is true and the cart contains age-restricted items.
3. Human (L1): Required if humanEnabled is true (applies to form protection, not checkout).

Priority order: L3 > L2 > L1. The highest applicable level is enforced.

Detection Modes

The server-side restricted detection service supports three modes, controlled by the detectionMode setting:

Age Gate Trigger Modes

The Age Gate theme extension embed supports four trigger modes that determine where the age verification overlay appears:

These trigger modes only control the storefront overlay (the age gate popup). Server-side checkout enforcement uses the vh_requires_age / vh_requires_idv tags and metafields independently.

Identity Verification Triggers

Identity verification can be triggered in multiple ways:

Pre-Checkout (Cart Page)

The identity-checkout embed monitors the cart page. If any cart item has the vh_requires_idv tag or the verifyhuman.requires_idv metafield set to true, the checkout button is intercepted and the verification modal is presented.

Settings:

• Require for All Checkouts — bypasses tag/metafield checks and requires verification for every checkout
• Product Tag — configurable tag name (default: vh_requires_idv)

Button-Triggered (Product Page)

The identity-block can be placed on any product page as an app block. It renders a "Verify My Identity" button that opens the verification modal when clicked.

Server-Side Enforcement

The cart checkout validation function runs at checkout and blocks the order if the required verification level is not met. This is the compliance-grade enforcement layer that cannot be bypassed by the customer.

Guest vs. Authenticated Checkout

Quick Reference: Tag and Metafield Summary