Concepts
Statistics and adoption
How your customers use Monotree, what each number means and how old it can be, and how to hear about a customer that stalls.
When the numbers land
Monotree counts each live customer once a night and keeps one set of numbers per customer per day. Everything on this page is built from those days, so it changes once a day and not while you watch.
- Days are UTC days.
updated_atis the day of the latest numbers, such as2026-11-14. - A customer's first numbers come the night after it goes live. Until then its totals are
0,dailyis empty andupdated_atisnull. - Numbers are normally less than a day old. If a night is missed,
updated_atstays where it was; after 3 days without numbers the customer gets an adoption alert with the reasonstale.
Every call here needs the customers:read ability. A sandbox token gets the sandbox's customers, a live token the live ones.
| Call | Answers |
|---|---|
| Get a customer's statistics | The numbers of one customer |
| Get the statistics of all customers | The same numbers for all your live customers together, and each customer beside the others |
| Get a customer's insights | What one customer's numbers mean, and what to do next |
| Get the headline numbers | Where you stand right now, in one small answer |
| List adoption alerts | The customers that stall |
The first three take range: 7d, 30d (when left out) or 90d. It is the last 7, 30 or 90 days, today included. Any other value answers 422.
One customer
curl "https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/statistics?range=7d" \
-H "Authorization: Bearer $MONOTREE_TOKEN"{
"object": "statistics",
"customer": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"range": "7d",
"updated_at": "2026-11-14",
"totals": {
"users": 8,
"invited": 9,
"active_users_7d": 7,
"activation_rate": 89,
"weekly_active_rate": 88,
"devices": { "ios": 4, "android": 3 },
"push_enabled_rate": 86
},
"period": { "posts": 3, "comments": 9, "reactions": 27, "messages": 48, "user_growth": 0 },
"languages": { "fr": 7, "en": 1 },
"daily": [
{ "date": "2026-11-13", "users": 8, "active_users": 4, "posts": 1, "comments": 2, "reactions": 5, "messages": 9 },
{ "date": "2026-11-14", "users": 8, "active_users": 2, "posts": 0, "comments": 1, "reactions": 3, "messages": 4 }
]
}(daily is cut short here: it has one row for each day in the range that has numbers, oldest first.)
| Field | Means |
|---|---|
totals.invited |
Employees the customer's admin has invited to the app |
totals.users |
Employees who registered in the app |
totals.activation_rate |
users as a percent of invited, rounded. 0 when nobody is invited |
totals.active_users_7d |
Users who opened the app in the last 7 days |
totals.weekly_active_rate |
active_users_7d as a percent of users, rounded. 0 when there are no users |
totals.devices |
Phones with the app, per platform (ios, android) |
totals.push_enabled_rate |
Percent of those phones with push notifications on |
period.posts, comments, reactions, messages |
Sums over the range |
period.user_growth |
Percent change in users since the day before the range began, with one decimal. null when the customer had no users or no numbers then |
languages |
Users per app language, by language code |
daily[].users |
Registered employees on that day |
daily[].active_users |
Users who opened the app that day |
totals are the latest day in the range. period and daily cover the range.
- The call answers for a customer in any status. A customer with no numbers in the range (a draft, or one that went live today) answers
0everywhere,"daily": [],"updated_at": nulland"user_growth": null. - When there are no numbers,
languagesis written as an empty list ([]) and not as an empty object. Treat both as "none". - Instead of the
cus_…ID you can writeexternal_ref:followed by your own reference, such as/customers/external_ref:org_48213/statistics.
All customers together
curl "https://partners.monotree.com/api/v1/statistics?range=7d" \
-H "Authorization: Bearer $MONOTREE_TOKEN"{
"object": "partner_statistics",
"range": "7d",
"updated_at": "2026-11-14",
"customers": 43,
"employees": 949,
"totals": { "users": 724, "invited": 947, "active_users_7d": 468, "activation_rate": 76, "weekly_active_rate": 65, "devices": { "ios": 392, "android": 274 }, "push_enabled_rate": 80 },
"period": { "posts": 147, "comments": 390, "reactions": 1450, "messages": 3019, "user_growth": 3.9 },
"languages": { "fr": 425, "es": 112, "en": 88, "it": 67, "nl": 17, "de": 15 },
"daily": [ { "date": "2026-11-14", "users": 724, "active_users": 160, "posts": 13, "comments": 29, "reactions": 128, "messages": 252 } ],
"customers_ranked": [
{
"customer": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"external_ref": "org_48213",
"seller": { "id": "sel_12", "name": "Emma Dubois", "external_ref": "usr_20503" },
"employees": 9,
"users": 8,
"activation_rate": 89,
"weekly_active_rate": 88,
"weekly_active_change": 0,
"activity": 87,
"adoption": null
},
{
"customer": "cus_01jd0b2q4m6s8u0w2y4a6c8e0g",
"company_name": "Librairie Voltaire",
"company_id": "librairievoltaire",
"external_ref": "org_51877",
"seller": { "id": "sel_12", "name": "Emma Dubois", "external_ref": "usr_20503" },
"employees": 21,
"users": 4,
"activation_rate": 19,
"weekly_active_rate": 75,
"weekly_active_change": 0,
"activity": 34,
"adoption": { "alert": "ala_01jd3m5p7r9t1v3x5z7b9d1f3h", "reason": "activation", "message": "Only 19% of invited employees have signed in, 126 days after going live" }
}
]
}- Only customers with the status
liveare counted: not suspended or cancelled ones.customerssays how many,employeeshow many employees they were signed up with. totalsadd up each customer's latest numbers, andupdated_atis the newest day among them.customers_rankedhas every live customer and is never paged. The best taken up comes first: the order isactivation_ratetimesweekly_active_rate, thenusers.activation_rateandweekly_active_rateof a customer arenulluntil its first numbers.weekly_active_changeis the weekly active rate now minus the rate on the day before the range began, in percentage points. It isnullwhen the customer had no users or no numbers then.activityis posts, comments, reactions and messages in the range.adoptionisnull, or the customer's open adoption alert.seller=narrows everything to one seller's customers:sel_…, orexternal_ref:and your own ID for the seller. An unknown seller answers404.sellerisnullon a customer made over the API without aseller_ref.
The headline numbers
Get the headline numbers takes no parameters and answers what stands on top of the Customers page in the portal:
{
"object": "summary",
"counts": { "draft": 1, "provisioning": 0, "live": 43, "failed": 1, "suspended": 2, "cancelled": 3 },
"live_customers": 43,
"employees": 949,
"users": 724,
"activation_rate": 76,
"weekly_active_rate": 65,
"low_adoption": 4,
"signed_by_month": [
{ "month": "2026-06", "signed": 6 },
{ "month": "2026-07", "signed": 7 },
{ "month": "2026-08", "signed": 6 },
{ "month": "2026-09", "signed": 5 },
{ "month": "2026-10", "signed": 5 },
{ "month": "2026-11", "signed": 7 }
]
}countsis how many customers are in each status right now. Deleted customers are not counted.employees,usersand the two rates are those of all live customers together.low_adoptionis how many live customers have an open adoption alert.signed_by_monthis the customers submitted in each of the last six months (UTC), oldest first and this month last.
Insights
Get a customer's insights answers what the Statistics tab of a customer shows in the portal:
{
"object": "insights",
"customer": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"range": "7d",
"live_days": 128,
"verdict": {
"key": "doing_well",
"title": "Doing well",
"text": "88% of its users came this week, more than your customers on average (64%).",
"next_step": "A good customer to ask for a quote or a reference."
},
"funnel": [
{ "key": "employees", "label": "Employees", "value": 9 },
{ "key": "invited", "label": "Invited", "value": 9 },
{ "key": "signed_in", "label": "Signed in", "value": 8 },
{ "key": "active_this_week", "label": "Active this week", "value": 7 }
],
"comparison": [
{ "key": "activation_rate", "label": "Signed in", "value": 89, "average": 76, "unit": "percent" },
{ "key": "weekly_active_rate", "label": "Active this week", "value": 88, "average": 64, "unit": "percent" },
{ "key": "activity_per_active_user", "label": "Activity per active user", "value": 12.4, "average": 10.7, "unit": "per_week" },
{ "key": "push_enabled_rate", "label": "Push notifications on", "value": 86, "average": 80, "unit": "percent" }
],
"activity": { "now": 87, "before": 92, "change": -5 },
"weekly_active_rate": [ { "date": "2026-11-14", "rate": 88, "average": 65 } ]
}The texts (title, text, next_step, label) are English sentences for a person and may be reworded. Build on the keys.
The verdict is the first of these that fits:
verdict.key |
When |
|---|---|
needs_attention |
The customer is live and has an open adoption alert. text is the alert's message, next_step its advice. |
getting_started |
It went live less than 14 days ago. |
doing_well |
Its weekly active rate is at or above that of your other live customers together. |
on_track |
Anything else. |
funnelis the rollout: the employees the customer was signed up with, theninvited,usersandactive_users_7dof its statistics.comparison[].averageis the same number for your other live customers together, without this one. It isnullwhen no other live customer has numbers.activity_per_active_useris posts, comments, reactions and messages a week for each user active in the last 7 days.activity.beforeis the period of the same length before the range, andchangethe percent between the two (nullwhenbeforeis0).weekly_active_ratehas one row for each day in the range the customer has numbers for.averageisnullon a day none of your other live customers has numbers for.- A customer that was never live answers
409with the error typeinvalid_state. A customer that was live and is now suspended or cancelled still answers.
Adoption alerts
An adoption alert says that a live customer stalls. Monotree checks every customer with the status live each morning at 05:00 UTC, after the night's numbers. The first rule that fits gives the alert its reason:
reason |
Raised when |
|---|---|
stale |
The latest numbers are 3 days old or more (or there are none), for a customer live 3 days or more. Monotree looks into these; there is nothing for you to do. |
activation |
Fewer than 30% of the invited employees have registered, with 5 or more invited. |
drop |
The weekly active rate is below half of what it was 4 weeks earlier, and it was 20% or more then. |
inactive |
The weekly active rate is below 20%. |
- The first 14 days after going live are a grace period: only
staleis raised in them. - A rate over fewer than 5 people is not judged:
activationneeds 5 invited employees,dropandinactiveneed 5 users (anddrop5 users 4 weeks earlier too). - A customer has at most one open alert. While it stays open, its
reasonandmessagefollow the latest numbers, without a new event. - The alert is resolved (
resolved_atis set) at the next morning's check when the customer no longer fits any rule, or is no longer live (suspended, cancelled or deleted). - A customer that stalls again within 14 days of
resolved_atre-opens the same alert: sameid, sameflagged_at, andresolved_atisnullagain. Later than that, it gets a new alert. - An alert cannot be closed by hand, in the portal or over the API.
{
"id": "ala_01jd3m5p7r9t1v3x5z7b9d1f3h",
"object": "adoption_alert",
"customer": { "id": "cus_01jd0b2q4m6s8u0w2y4a6c8e0g", "company_name": "Librairie Voltaire", "external_ref": "org_51877" },
"reason": "activation",
"message": "Only 19% of invited employees have signed in, 126 days after going live",
"advice": "Ask Louis Arnaud to invite the team again, or to share the company ID librairievoltaire at the next staff meeting.",
"flagged_at": "2026-11-14T05:00:04Z",
"resolved_at": null
}message and advice are English sentences for a person and may be reworded; build on reason. flagged_at is when the alert was first raised.
Reading alerts
List adoption alerts gives the open ones. status=resolved or status=all gives the others; customer= (a cus_… ID, or external_ref: and your own reference), seller= (a sel_… ID, or external_ref: and your own reference) and reason= filter. An unknown customer or seller answers 404. The list is paged like every list (limit, cursor), the alert made last first. Get an adoption alert answers one.
curl "https://partners.monotree.com/api/v1/adoption-alerts?reason=activation" \
-H "Authorization: Bearer $MONOTREE_TOKEN"The customer itself carries its open alert too. Get a customer has adoption, which is null when the customer has no open alert:
{
"adoption": {
"alert": "ala_01jd3m5p7r9t1v3x5z7b9d1f3h",
"reason": "activation",
"message": "Only 19% of invited employees have signed in, 126 days after going live",
"flagged_at": "2026-11-14T05:00:04Z"
}
}List customers with adoption=stalling gives only the customers with an open alert.
Events
| Event | Sent when |
|---|---|
adoption.alert.raised |
The morning check opens an alert, or re-opens one after the customer had recovered |
adoption.alert.resolved |
The morning check closes the alert: the customer recovered, or is no longer live |
Both carry the alert in data.adoption_alert, in the shape above, and nothing else in data. Their actor is null. They are sent once per change, not every morning the alert stays open, and not when only reason or message change. See Webhooks for how to receive them.
{
"id": "evt_01jd3m5p9c2e4g6j8m0p2r4t6v",
"object": "event",
"type": "adoption.alert.raised",
"created_at": "2026-11-14T05:00:04Z",
"sandbox": false,
"actor": null,
"data": {
"adoption_alert": {
"id": "ala_01jd3m5p7r9t1v3x5z7b9d1f3h",
"object": "adoption_alert",
"customer": { "id": "cus_01jd0b2q4m6s8u0w2y4a6c8e0g", "company_name": "Librairie Voltaire", "external_ref": "org_51877" },
"reason": "activation",
"message": "Only 19% of invited employees have signed in, 126 days after going live",
"advice": "Ask Louis Arnaud to invite the team again, or to share the company ID librairievoltaire at the next staff meeting.",
"flagged_at": "2026-11-14T05:00:04Z",
"resolved_at": null
}
}
}(The event also has api_version, as every event does.)
In the sandbox
Sandbox customers never reach Monotree's platform, so nobody uses them. Their numbers are made up: a team that signs in over three weeks, busier on weekdays than at weekends. The same customer always gets the same numbers.
- The made-up numbers are written each morning at 04:30 UTC, not at once. A sandbox customer has no numbers on the day it goes live; its first ones come the next morning.
- The adoption check at 05:00 UTC judges sandbox customers by the same rules as live ones. A normal sandbox team is busy enough not to stall.
- To get an alert on purpose, give the customer a company ID that starts with
stall, such asstalltest, and 10 employees or more. Only about 18% of its team signs in and the 14 days of grace are skipped, so it has an alert with the reasonactivation, and you getadoption.alert.raised, at the first check after the day it goes live. See Sandbox and testing. - Statistics, insights, alerts and both events work with a sandbox token and stay in the sandbox: sandbox numbers are never mixed into live ones, and the events go only to your sandbox webhook endpoints.
- The Monday email about customers that stall never mentions a sandbox customer.
What still needs the portal
- The charts. The API gives the numbers behind them.
- The Monday email about customers that stall, sent to your sellers and admins. Each person turns it off on their account page; over the API it is
adoption_digestof a seller.
There is no endpoint that changes anything on this page: the numbers, the rules and their thresholds are Monotree's.