Core concepts

Almost every question about Evident’s behaviour resolves to “which object is this hanging off”. This page defines them once.

The data model

Object	What it is
Organization	Your account. Holds users, billing, and one or more stores. Everything else is scoped beneath it.
Store environment	A single connected storefront. Identified by a store environment ID, which is the value you will pass as x-store-env-id on API calls and data-store-env-id in the widget script.
Product	One catalogue item, keyed by the platform’s own product ID. Reviews, FAQs and star badges attach to it.
Order	A purchase, with line items linking to products. The trigger for review requests, verified-purchase status, and loyalty accrual.
Review	A rating, title, body, and optional photos or video, in one of several moderation states.
Loyalty account	A customer’s points balance, lifetime points, tier, and referral code. Keyed on email within a store.
FAQ	A question and answer, scoped to a product, category, page, blog post, or the whole store.
Gallery	A named, ordered collection of images and videos with a slug you embed by.

An organization can hold several stores, and a user can belong to several organizations. Your email address is not globally unique in Evident — it is unique within an organization. That matters when you are invited to a client’s account and already have your own.

Store environments

Every store you connect creates one store environment. New connections are created as PRODUCTION; the concept exists so that a store can later have staging and development environments without their data mixing.

The store environment ID is the tenancy boundary. Every widget, every API key, and every request carries one, and Evident refuses queries that do not name a tenant. Two stores in the same organization cannot see each other’s reviews.

Where data comes from

There are two ways in, and a store uses one or the other:

• Platform sync. Connect BigCommerce or Shopify and Evident pulls the catalogue, backfills recent orders, and registers webhooks so later changes arrive on their own.
• API push. A headless or custom storefront sends PUT /products and PUT /orders itself. Both are upserts keyed on your IDs, so re-sending the same payload is safe.

Both paths land in the same tables. A widget cannot tell the difference.

Orders are the spine

This is the part that surprises people, so it is worth stating flatly.

• A review request is scheduled off an order reaching a qualifying status — “Shipped” by default, configurable per store.
• Verified purchase is decided by matching the reviewer’s email to an order containing that product. No matching order, no badge.
• Loyalty points for a purchase are derived from orders, not pushed at you: a qualifying order with no award yet gets one within about ten minutes of the status change.

The clock in all three cases starts at the status change, not at the moment the order was created or imported.

Review states

A review is in exactly one state:

• Pending — submitted, not yet visible on the storefront.
• Approved — visible.
• Rejected — kept for the record, never shown.

Auto-approval for verified purchases is a per-store setting. Rejecting is not deleting: the row stays so that the same customer cannot quietly resubmit the same complaint and so your audit trail is complete.

Approved reviews are ordered by their published date, falling back to their creation date, so an imported corpus keeps its original chronology rather than all landing on your migration day.

Which surface do I need?

• Rendering something to a shopper → the widget SDK. No key required; access is controlled by an origin allow-list.
• Reading or writing data from your own systems → the REST API with an evnt_ key.
• Letting an AI assistant read or act → the MCP server, which wraps the same API with the same permissions.