> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quivly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Product Adoption

> Monitor product usage metrics, score them in health, and turn drops or surges into drafted actions.

## Overview

Adoption in Quivly is the usage metrics you sync — events, seats, API volume, or whatever you map from your warehouse, PostHog, or the Push API — shown on the customer and folded into the **Product Usage** health category.

Use this workflow to:

* Confirm usage data is connected and mapped to customers
* Read trends on the [Usage tab](/customer-views/usage-tab)
* Put usage columns and filters on the [customer list](/customer-views/customer-list)
* Score usage in [health configuration](/health-scores/configuration)
* Draft outreach when usage drops or surges

Quivly does not write usage back to your product analytics or warehouse.

***

## What you need connected

Pick at least one product-usage source:

| Source                                                                                           | How it connects                           |
| ------------------------------------------------------------------------------------------------ | ----------------------------------------- |
| [Snowflake](/integrations/warehouses/snowflake) or [BigQuery](/integrations/warehouses/bigquery) | Credentials; Quivly queries on a schedule |
| [PostHog](/integrations/product-usage/posthog)                                                   | OAuth or API key                          |
| [Usage Push API](/integrations/product-usage/api-overview)                                       | HTTP events from your backend             |

Customers must [link](/field-mappings/cross-system-linking) to those records (domain, external ID, or your mapping). A metric with no matching customer does not appear on a profile.

***

## Read the Usage tab

Open a customer → **Usage**.

### Time range and granularity

| Control         | Options                                                       |
| --------------- | ------------------------------------------------------------- |
| **Time range**  | Last 7 / 30 / 90 days, MTD, QTD, YTD, or a custom range       |
| **Granularity** | Daily, weekly, or monthly — applies to every chart on the tab |

### Metric summary row

Up to six metrics across the top. Each card shows label, current value, a sparkline, and a trend percentage (up / down / flat). Click a card to highlight its chart.

### Charts

* **Product-grouped view** — when metrics are associated with products, they sit in collapsible product sections.
* **Flat view** — each metric is a time-series chart titled with the metric name and "Over Time", with a trend badge (growing, declining, or stable over the selected period).

Hover a chart for date and value. Color follows trend: green growth, red decline, indigo stable.

***

## Build a working list

<Steps>
  <Step title="Open Customers">
    Click **Customers**. Use **My Accounts** if you only want your book.
  </Step>

  <Step title="Add usage columns">
    Any product usage metric can be a column, with period options **30d / 60d / 90d / 180d / 1y** and a trend indicator. Add the metrics you treat as adoption (for example weekly active users, or a core feature event).
  </Step>

  <Step title="Filter">
    Use numeric operators on those metrics: equals, greater than, less than, is empty, has value. Combine with **Health Risk Level** when a usage drop should only surface on unhealthy accounts.

    Save as a [custom view](/customer-views/custom-views) (for example "Usage down 30d").
  </Step>

  <Step title="Sort">
    Sort the usage column ascending to put the quietest accounts first, or by health score if risk should lead.
  </Step>
</Steps>

<Warning>
  If a usage column is empty for most rows, the warehouse/PostHog/Push source is not published, the metric is not mapped, or customers are not linking. See [customer information not linking](/troubleshooting/customer-information-not-linking).
</Warning>

***

## Score usage in health

Product Usage is one of five health categories. Enable it and set its weight under **Settings → Health Scores**. Weights for enabled categories must total 100%.

### Lookback

Product usage metrics support **30d, 60d, 90d, 180d, 1y**.

### Scoring methods

| Method                  | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| **Trend + Volume**      | Combines usage volume with trend direction (recommended) |
| **Absolute Value**      | Score from raw usage numbers                             |
| **Growth Percentage**   | Score from percentage change vs the previous period      |
| **Absolute Difference** | Score from change in units vs the previous period        |

Each metric (except Market Signals) uses three thresholds that create four buckets, plus a direction (higher-is-better vs lower-is-better). See [configuration](/health-scores/configuration).

If a usage metric was configured and its data source is later removed, it shows as an orphaned metric with a warning badge. Save a draft, then [publish](/health-scores/configuration#saving-and-publishing) after you test.

On the customer **Health Score** tab, expand **Product Usage** for the category score, weight, contribution, and evidence. A declining usage category with a high weight is the usual adoption-risk pattern.

***

## Act

| Job                                                                         | Where                                                                                                      |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Explain why usage fell on one account                                       | [Ask Quivly](/product/ask-quivly), or a usage [skill](/product/skills) in a [notebook](/product/notebooks) |
| Draft a recommendation on a usage drop or surge                             | [Signal rules](/product/signal-rules) — triggers **usage drops** or **usage surges**                       |
| Run a scheduled or threshold workflow (lookups → skill → Review → outreach) | [Agents](/product/agents) — template **Expansion spotter** (usage crosses a threshold)                     |
| Review and send the draft                                                   | [Actions](/product/actions)                                                                                |

Signal-rule recommendations are always drafts. Use the sensitivity dial and quiet period so a noisy metric does not refill the inbox every day.

For expansion: high volume plus a healthy score is a stronger signal than high volume on a Critical account. Put health context next to usage before you pitch a plan change.

***

## Dashboards

The dashboard template library includes a **Product** category. Number and line widgets on usage metrics, filtered by segment or health bucket, give you a portfolio view the customer list cannot. See [dashboards](/dashboards/introduction).

***

## FAQ

<AccordionGroup>
  <Accordion title="Does Quivly track individual feature flags or session replay?">
    Quivly scores the usage metrics you map. Feature-level adoption exists only if you send those events as metrics (warehouse, PostHog, or Push API) and attach them to customers.
  </Accordion>

  <Accordion title="Why is the Usage tab empty for a customer who is paying?">
    Billing and usage are separate integrations. Paying in Stripe does not create warehouse rows. Confirm the usage source is published and the customer links on the identifier you map.
  </Accordion>

  <Accordion title="Can Ask Quivly or a skill change usage data?">
    No. Usage tools are read-only. Outbound follow-up goes through agent steps or Actions you review.
  </Accordion>
</AccordionGroup>

***

## Related guides

<CardGroup cols={2}>
  <Card title="Identifying at-risk customers" icon="triangle-exclamation" href="/workflows/identifying-at-risk-customers">
    Health-score workflow, including usage decline patterns
  </Card>

  <Card title="Revenue management" icon="dollar-sign" href="/workflows/revenue-management">
    Renewals, invoices, and expansion pipeline
  </Card>

  <Card title="Usage tab" icon="chart-line-up" href="/customer-views/usage-tab">
    Time range, granularity, and chart layouts
  </Card>

  <Card title="Warehouse overview" icon="database" href="/integrations/warehouses/overview">
    How product usage gets into Quivly
  </Card>
</CardGroup>