Skip to main content

Metafields

Real ID automatically syncs the status of your ID checks to BigCommerce orders and customers using metafields. It writes two metafields under the realid namespace:

  • realid.check_id - the specific ID check associated with this customer or order
  • realid.verification_status - the current status of the ID check

These metafields are updated automatically as customers progress through their ID verification.

realid.verification_status Metafield​

This metafield is present on both the order and the customer. It reflects the current state of the ID check and is kept in sync during the customer's ID verification lifecycle.

Here are all of the possible values:

  • pending - the ID check has been created but the customer has not opened it yet
  • in_progress - the customer has opened the ID check and is actively verifying
  • in_review - the ID check has warnings (such as an expired ID) that require manual approval
  • failed - the ID check failed conclusively
  • verified - the customer successfully completed their ID check
  • manually_approved - a staff member manually approved the ID check
  • manually_rejected - a staff member manually rejected the ID check
note

These metafields will only be present on orders or customers that have an associated ID check. If you have trigger rules configured that only require ID verification under specific conditions, orders that don't match those conditions won't have these metafields.

realid.check_id Metafield​

This metafield is present on both the order and the customer. It contains the unique token that references the customer's most recent ID check.

You can use this token as the ID parameter for retrieving the details of the ID check with the Real ID REST API.

Manually creating new ID checks will overwrite the realid.check_id metafield. If the customer is already verified then a new ID check will replace the current value.

Viewing Metafields​

You can view the metafields for an order or customer through the BigCommerce API. Use the BigCommerce Metafields API to retrieve them programmatically.

Order metafields​

GET /stores/{store_hash}/v3/orders/{order_id}/metafields

Customer metafields​

GET /stores/{store_hash}/v3/customers/{customer_id}/metafields

Example response​

{
  "data": [
    {
      "namespace": "realid",
      "key": "verification_status",
      "value": "verified",
      "permission_set": "read"
    },
    {
      "namespace": "realid",
      "key": "check_id",
      "value": "abc123def456",
      "permission_set": "read"
    }
  ]
}

How metafields are synchronized​

Real ID sends updates to BigCommerce as customers progress through their ID check. Metafields are updated at each stage:

  1. Check created - metafields are set to pending
  2. Customer opens the check - status updates to in_progress
  3. Customer submits photos - status remains in_progress
  4. Verification completes - status updates to verified or failed
  5. Manual override - status updates to manually_approved or manually_rejected

These updates are processed asynchronously, so there may be a brief delay between the customer's action and the metafield update appearing in BigCommerce.