Before Checkout Verification

Before checkout verification requires customers to verify their ID before they can complete their purchase. This prevents orders from unverified customers entirely.

How it works

1. Customer adds items to cart and proceeds to checkout
2. Before they can enter payment information, the ID verification prompt appears
3. Customer must complete verification to continue
4. Once verified, they can complete their purchase

Setup

Step 1: Install the Real ID App

1. Visit the Real ID app listing in the BigCommerce App Marketplace
2. Click Install and authorize the app for your store
3. You'll be redirected to the Real ID dashboard

Step 2: Configure Before Checkout Flow

1. In the Real ID dashboard, go to Settings > Automations
2. Enable Automated ID checks
3. Select Before checkout as your verification flow
4. Configure your trigger rules (see Built-in Triggers below)
5. Click Save

That's it! The Real ID verification script is automatically installed on your checkout page.

Built-in Triggers

Configure which customers should be prompted for ID verification. These options require no code - just toggle them on in the Real ID dashboard.

Verify all orders

Require ID verification for every checkout. When enabled, all other trigger rules are ignored.

Cart value threshold

Require ID verification only for carts above a certain amount. Set your minimum cart value (e.g., $100) and only high-value orders will require verification.

Product categories

Require ID verification for carts containing products from specific categories. Select which product categories should trigger verification - useful for age-restricted items like alcohol, tobacco, or firearms.

U.S. shipping states

Require ID verification only for orders shipping to the United States. You can further narrow this to specific states - useful for complying with state-specific regulations.

Combining Triggers

When multiple triggers are enabled, verification is required if any rule matches. For example, if you enable both "Cart value threshold ($100)" and "Product categories (Alcohol)", a $50 order with alcohol OR a $150 order without alcohol will both require verification.

Customer experience

When before checkout verification is enabled:

• Customers shop and add items to cart normally
• When they proceed to checkout, the verification prompt appears
• They must complete ID verification before entering payment details
• Already-verified customers skip the verification step automatically

Frequently Asked Questions

Will this slow down checkout for all customers?

No. Real ID remembers verified customers. Returning customers who have already verified their ID will proceed directly to checkout without seeing the verification prompt again.

Can I require verification only for certain products or orders?

Yes! Use the built-in triggers above to configure rules based on order value, specific product categories, or customer location. For more complex conditions, see the Custom Trigger Scripts section below.

What if a customer can't complete verification?

If a customer is unable to verify their ID, they won't be able to complete checkout. You can review failed verification attempts in your Real ID dashboard and contact the customer if needed.

Is this compatible with all BigCommerce themes?

Before checkout verification works with most BigCommerce themes. If you experience any display issues, please contact our support team.

Can customers save their cart and verify later?

Yes. If a customer leaves during verification, their cart is preserved. When they return and try to checkout again, they'll be prompted to complete verification.

Custom Trigger Scripts

For merchants who need custom trigger logic beyond the built-in options, you can create scripts that conditionally trigger ID verification using the Real ID JS SDK.

SDK Already Loaded

The Real ID SDK is automatically loaded on your checkout page when you enable before checkout verification. You only need to add a custom script with your trigger logic - no need to add the SDK separately.

How Custom Triggers Work

1. Your custom script evaluates conditions using BigCommerce Storefront APIs
2. If conditions are met, your script calls RealID.createFlow() to trigger verification
3. The SDK handles the rest - displaying the verification UI and processing the result

Adding a Custom Trigger Script

1. In BigCommerce admin, go to Storefront > Script Manager
2. Click Create a Script
3. Fill in the following:
   • Name: Real ID Custom Trigger
   • Description: Custom ID verification trigger
   • Location on page: Footer
   • Select pages where script will be added: Checkout
   • Script category: Essential
   • Script type: Script
4. Paste one of the example scripts below
5. Click Save

Multi-step Checkout

BigCommerce uses a multi-step checkout where elements appear dynamically. The examples below include a waitForSelector helper function that waits for the "Place Order" button to appear before triggering verification.

Finding Your Store Hash

Each example requires your BigCommerce store hash - a unique identifier for your store. You can find it in:

• Your BigCommerce admin URL: https://store-{STORE_HASH}.mybigcommerce.com/manage/...
• Example: If your URL is store-abc123xyz.mybigcommerce.com, your store hash is abc123xyz

Replace YOUR_STORE_HASH in the examples below with your actual store hash.

Example 1: Specific State AND Product Category (Combined)

Trigger verification only when BOTH conditions are met: shipping to California AND cart contains products from specific categories.

<script>
// Helper: Wait for an element to appear in the DOM
function waitForSelector(selector, timeoutMs) {
  timeoutMs = timeoutMs || 30000;
  return new Promise(function(resolve) {
    var existing = document.querySelector(selector);
    if (existing) { resolve(existing); return; }
    var observer = new MutationObserver(function(mutations, obs) {
      var element = document.querySelector(selector);
      if (element) { obs.disconnect(); resolve(element); }
    });
    observer.observe(document.body, { childList: true, subtree: true });
    setTimeout(function() { observer.disconnect(); resolve(null); }, timeoutMs);
  });
}

// Real ID - Verify orders shipping to CA with products in specific categories
(async function() {
  var STORE_HASH = 'YOUR_STORE_HASH'; // Replace with your store hash
  var REQUIRED_STATE = 'CA'; // State code to require verification
  var REQUIRED_CATEGORY_IDS = [23, 45, 67]; // Customize with your category IDs
  console.log('Real ID: Checking for state=' + REQUIRED_STATE + ' AND categories=' + REQUIRED_CATEGORY_IDS.join(', '));

  try {
    // Step 1: Check shipping state
    var cartResponse = await fetch('/api/storefront/carts');
    var carts = await cartResponse.json();
    var cart = carts[0];

    if (!cart) {
      console.log('Real ID: No cart found');
      return;
    }

    var checkoutResponse = await fetch('/api/storefront/checkouts/' + cart.id);
    var checkout = await checkoutResponse.json();

    var shippingAddress = checkout.consignments &&
                          checkout.consignments[0] &&
                          checkout.consignments[0].shippingAddress;

    if (!shippingAddress) {
      console.log('Real ID: No shipping address entered yet');
      return;
    }

    console.log('Real ID: Shipping to ' + shippingAddress.stateOrProvinceCode + ', ' + shippingAddress.countryCode);

    var stateMatches = shippingAddress.countryCode === 'US' &&
                       shippingAddress.stateOrProvinceCode === REQUIRED_STATE;

    if (!stateMatches) {
      console.log('Real ID: State does not match ' + REQUIRED_STATE + ', skipping verification');
      return;
    }

    console.log('Real ID: State matches ' + REQUIRED_STATE + ', checking product categories...');

    // Step 2: Check product categories
    var allItems = (cart.lineItems.physicalItems || [])
      .concat(cart.lineItems.digitalItems || []);
    var productIds = allItems.map(function(item) { return item.productId; });

    if (productIds.length === 0) {
      console.log('Real ID: No products in cart');
      return;
    }

    var query = '{ site { products(entityIds: [' + productIds.join(',') + '], first: 50) { edges { node { entityId categories { edges { node { entityId } } } } } } } }';
    var gqlResponse = await fetch('/graphql', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ query: query })
    });
    var gqlData = await gqlResponse.json();

    var products = gqlData.data && gqlData.data.site && gqlData.data.site.products && gqlData.data.site.products.edges || [];
    var categoryMatches = products.some(function(productEdge) {
      var categories = productEdge.node.categories && productEdge.node.categories.edges || [];
      return categories.some(function(catEdge) {
        return REQUIRED_CATEGORY_IDS.includes(catEdge.node.entityId);
      });
    });

    if (!categoryMatches) {
      console.log('Real ID: No products in required categories, skipping verification');
      return;
    }

    console.log('Real ID: Both conditions met! Triggering verification');

    // Wait for the Place Order button
    var placeOrderBtn = await waitForSelector('#checkout-payment-continue');
    if (placeOrderBtn) {
      RealID.createFlow({
        target: "#checkout-payment-continue",
        mode: "modal",
        shopName: STORE_HASH
      });
    }
  } catch (e) {
    console.error('Real ID: Error checking conditions', e);
  }
})();
</script>

Finding Category IDs

To find your category IDs, go to Products > Product Categories in your BigCommerce admin. Click on a category - the ID is shown in the URL (e.g., /manage/categories/23 means the ID is 23).

Example 2: Specific State AND Custom Field (Combined)

Trigger verification only when BOTH conditions are met: shipping to California AND cart contains products with the id_verification_required custom field.

<script>
// Helper: Wait for an element to appear in the DOM
function waitForSelector(selector, timeoutMs) {
  timeoutMs = timeoutMs || 30000;
  return new Promise(function(resolve) {
    var existing = document.querySelector(selector);
    if (existing) { resolve(existing); return; }
    var observer = new MutationObserver(function(mutations, obs) {
      var element = document.querySelector(selector);
      if (element) { obs.disconnect(); resolve(element); }
    });
    observer.observe(document.body, { childList: true, subtree: true });
    setTimeout(function() { observer.disconnect(); resolve(null); }, timeoutMs);
  });
}

// Real ID - Verify orders shipping to CA with products that have "id_verification_required" custom field
(async function() {
  var STORE_HASH = 'YOUR_STORE_HASH'; // Replace with your store hash
  var REQUIRED_STATE = 'CA'; // State code to require verification
  var CUSTOM_FIELD_NAME = 'id_verification_required'; // Custom field name
  console.log('Real ID: Checking for state=' + REQUIRED_STATE + ' AND custom field="' + CUSTOM_FIELD_NAME + '"');

  try {
    // Step 1: Check shipping state
    var cartResponse = await fetch('/api/storefront/carts');
    var carts = await cartResponse.json();
    var cart = carts[0];

    if (!cart) {
      console.log('Real ID: No cart found');
      return;
    }

    var checkoutResponse = await fetch('/api/storefront/checkouts/' + cart.id);
    var checkout = await checkoutResponse.json();

    var shippingAddress = checkout.consignments &&
                          checkout.consignments[0] &&
                          checkout.consignments[0].shippingAddress;

    if (!shippingAddress) {
      console.log('Real ID: No shipping address entered yet');
      return;
    }

    console.log('Real ID: Shipping to ' + shippingAddress.stateOrProvinceCode + ', ' + shippingAddress.countryCode);

    var stateMatches = shippingAddress.countryCode === 'US' &&
                       shippingAddress.stateOrProvinceCode === REQUIRED_STATE;

    if (!stateMatches) {
      console.log('Real ID: State does not match ' + REQUIRED_STATE + ', skipping verification');
      return;
    }

    console.log('Real ID: State matches ' + REQUIRED_STATE + ', checking product custom fields...');

    // Step 2: Check product custom fields
    var allItems = (cart.lineItems.physicalItems || [])
      .concat(cart.lineItems.digitalItems || []);
    var productIds = allItems.map(function(item) { return item.productId; });

    if (productIds.length === 0) {
      console.log('Real ID: No products in cart');
      return;
    }

    var query = '{ site { products(entityIds: [' + productIds.join(',') + '], first: 50) { edges { node { entityId customFields { edges { node { name value } } } } } } } }';
    var gqlResponse = await fetch('/graphql', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ query: query })
    });
    var gqlData = await gqlResponse.json();

    var products = gqlData.data && gqlData.data.site && gqlData.data.site.products && gqlData.data.site.products.edges || [];
    var customFieldMatches = products.some(function(productEdge) {
      var customFields = productEdge.node.customFields && productEdge.node.customFields.edges || [];
      return customFields.some(function(fieldEdge) {
        return fieldEdge.node.name === CUSTOM_FIELD_NAME &&
               fieldEdge.node.value.toLowerCase() === 'true';
      });
    });

    if (!customFieldMatches) {
      console.log('Real ID: No products have "' + CUSTOM_FIELD_NAME + '" = true, skipping verification');
      return;
    }

    console.log('Real ID: Both conditions met! Triggering verification');

    // Wait for the Place Order button
    var placeOrderBtn = await waitForSelector('#checkout-payment-continue');
    if (placeOrderBtn) {
      RealID.createFlow({
        target: "#checkout-payment-continue",
        mode: "modal",
        shopName: STORE_HASH
      });
    }
  } catch (e) {
    console.error('Real ID: Error checking conditions', e);
  }
})();
</script>

Creating Custom Fields

To add a custom field to a product:

1. Go to Products > View in BigCommerce admin
2. Edit the product
3. Scroll to Custom Fields
4. Add a field with name id_verification_required and value true
5. Save the product

Combining Conditions

These examples demonstrate AND logic - both conditions must be true. You can adapt this pattern to combine any conditions:

• Change REQUIRED_STATE to any US state code (e.g., 'NY', 'TX')
• Add multiple states by changing the check to ['CA', 'NY'].includes(shippingAddress.stateOrProvinceCode)
• Combine with cart total checks by adding cart.cartAmount >= MINIMUM_AMOUNT

Learn More

For more information about the Real ID JS SDK, including theming options and prepopulating customer data, see our JavaScript SDK documentation.