> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.ecomx.co/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Commerce Surface Health

# Commerce surface health

The Health page checks whether AgentWatch can read required Shopify data and
whether selected machine-facing commerce capabilities are discoverable.

Health checks are read-only. The cart check verifies whether a capability is
advertised; it does not add products to a cart or perform checkout actions.

## The seven health checks

### Shopify analytics access

Confirms that AgentWatch can submit an authenticated, read-only ShopifyQL
query. An access warning commonly means report permissions or protected
customer data approval are unavailable.

### Global Catalog analytics

Confirms that Shopify accepts the Global Catalog analytics query. A successful
query with no rows is valid and does not mean the catalog is unavailable.

### AI commerce connection

Checks whether the storefront commerce endpoint returns a valid machine-readable
response.

### Product discovery tools

Checks whether the required read-only catalog search, lookup, and product tools
are advertised.

### Product visibility

Uses an active store product for a safe, read-only lookup and checks whether the
returned product matches the merchant-owned product. If the store has no active
product, the result is **Unknown** instead of a failure.

### Cart capability

Checks whether the storefront advertises cart support for AI agents. No cart
mutation is performed.

### Policies and FAQs

Checks whether the policy and FAQ endpoint responds and advertises its required
read-only discovery tool.

## Health statuses

- **Healthy — Working as expected:** the check passed.
- **Warning — Needs attention:** the check returned an unexpected or
  unavailable result.
- **Critical — Currently unavailable:** repeated failures have reached the
  critical incident threshold.
- **Unknown — Could not be verified:** AgentWatch lacked a safe test condition,
  such as an active product.

## Run checks manually

Select **Run health checks** at the top of the Health page. Manual checks have a
one-minute cooldown. Running checks repeatedly does not make completed-day
analytics arrive sooner.

The latest run shows:

- The overall status.
- When the run started.
- Whether it was manual, scheduled, or installation-triggered.
- Each check's response time and plain-language summary.

Expand **View technical details** when troubleshooting. These details are
sanitized, but you should still avoid copying unrelated store or customer data
into a support message.

## When a health incident opens

AgentWatch avoids opening an incident for a single temporary failure:

- Two consecutive failures open a Warning incident.
- Three consecutive failures escalate it to Critical.
- Two consecutive healthy runs resolve it automatically.

Some conditions are informational and do not create incidents. For example,
blocked analytics access and the absence of a safe active product have their
own setup or Unknown states.

## Recent history

The Health page keeps the 10 most recent health runs visible. Use the history
to distinguish a persistent problem from a one-time response or network issue.

Next: [Global Catalog product exposure](05-product-exposure.md)