Concepts
The monthly statement
What Monotree counts for a month, how to read it over the API, and how to check it against your own records.
What counts
The statement of a month counts the customers that are live at the end of the last day of the month. A customer counts when:
- it went live on or before that day;
- it was not cancelled on or before that day (a customer cancelled on the 31st does not count for that month);
- it is not suspended. A customer that was suspended on or before that day, and still is, does not count.
The overview is this count. It has no prices and no amounts: the API gives the numbers the statement is built on, not the statement itself.
For the month that is still running, the moment is now and complete is false: the numbers move until the month ends.
A customer deleted later still counts for the months in which it was live.
Which clock
Months start and end at midnight UTC, for every partner. A customer that goes live on 1 November at 00:30 in Paris went live on 31 October at 23:30 UTC, so it is live on the last day of October and counts in October's statement. Dates such as live_at in the overview are UTC dates too.
A month
Get a month answers the month as the statement counts it. It needs the customers:read ability.
curl "https://partners.monotree.com/api/v1/overview?month=2026-10" \
-H "Authorization: Bearer $MONOTREE_TOKEN"{
"object": "overview",
"month": "2026-10",
"complete": true,
"live_customers": 39,
"employees": 894,
"users": 702,
"signed": 5,
"cancelled": 2,
"sellers": [
{ "seller": { "id": "sel_12", "name": "Emma Dubois", "external_ref": "usr_20503" }, "customers": 10, "employees": 254, "users": 208, "signed": 1 }
],
"customers": [
{
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"external_ref": "org_48213",
"seller": { "id": "sel_12", "name": "Emma Dubois", "external_ref": "usr_20503" },
"live_at": "2026-07-09",
"employees": 9,
"users": 8
}
]
}| Field | Means |
|---|---|
complete |
true once the month is over, false for the month that runs |
live_customers |
Customers that count for the month, as above |
employees |
The employees those customers were signed up with |
users |
Their employees registered in the app, by each customer's latest numbers on or before the last day of the month. A customer without numbers yet adds 0 |
signed |
Customers submitted in the month, whether or not they went live or still exist |
cancelled |
Customers cancelled in the month that had been live |
sellers |
The same numbers per seller, the seller with most live customers first. A seller is listed when they have a customer that counts or signed one in the month. seller is null for customers made over the API without a seller_ref |
customers |
One row for every customer counted in live_customers, by company name from A to Z. All of them: the list is not paged |
monthisYYYY-MM. Left out, it is this month.- You can ask for any month from your first month with Monotree to this month. A month in the future, before your first month, or not a month at all (
2026-13,2026-1) answers422with the error typevalidation_error; the message names the months you can ask for. seller=narrows the whole answer to one seller's customers:sel_…, orexternal_ref:and your own ID for the seller. An unknown seller answers404.- With a sandbox token the month counts your sandbox customers. They are never on a statement.
Twelve months at a glance
List the last 12 months gives the trend: up to twelve rows, oldest first and this month last. It lists only months Get a month answers for, so it starts at your first month with Monotree when that is less than a year ago. It takes the same seller.
curl "https://partners.monotree.com/api/v1/overview/months" \
-H "Authorization: Bearer $MONOTREE_TOKEN"{
"object": "list",
"data": [
{ "month": "2026-09", "live_customers": 37, "signed": 5 },
{ "month": "2026-10", "live_customers": 39, "signed": 5 },
{ "month": "2026-11", "live_customers": 43, "signed": 7 }
],
"has_more": false,
"next_cursor": null
}(Cut short here: the answer has twelve rows.)
live_customersof a month is the same number as in that month's overview.- The list is not paged, so it has no
has_moreornext_cursor. - A month before your first customer has zeros. Such a month is in this list even when it lies before your first month with Monotree, where Get a month answers
422.
As a spreadsheet
Add format=csv to Get a month, or send the header Accept: text/csv, to get the customers of the month as a CSV file. format wins when you send both. month and seller work as above.
curl "https://partners.monotree.com/api/v1/overview?month=2026-10&format=csv" \
-H "Authorization: Bearer $MONOTREE_TOKEN" -o monotree-2026-10.csv"Customer ID",Company,"Company ID","External ref",Seller,"Live since",Employees,"Monotree users"
cus_01jcz8w3k1x9q2v7s4e6m0b5n8,"Boulangerie Martin",boulangeriemartin,org_48213,"Emma Dubois",2026-07-09,9,8
cus_01jd0b2q4m6s8u0w2y4a6c8e0g,"Librairie Voltaire",librairievoltaire,org_51877,"Emma Dubois",2026-07-11,21,4The columns, in this order:
| Column | Is |
|---|---|
Customer ID |
id (cus_…) |
Company |
company_name |
Company ID |
company_id |
External ref |
external_ref, empty when the customer has none |
Seller |
The seller's name, empty when the customer has no seller |
Live since |
live_at, a UTC date |
Employees |
employees |
Monotree users |
users |
- The file has one heading row and one row for each customer in
customers, in the same order. It has no totals and no per-seller rows. - It is UTF-8, comes as
text/csv; charset=utf-8and is namedmonotree-2026-10.csv. It starts with a byte order mark (the three bytesEF BB BF), so Excel shows accented names right; most CSV readers skip it, and if yours does not, drop the first three bytes. - A value that starts with
=,+,-or@gets a'in front, so a spreadsheet shows it as text and does not run it as a formula. - It is the file Export CSV gives on the Overview page of the portal. The API's headings are always English; the portal's are in the language of the person who exports.
Reconciling with your own records
- Once a month is over (
complete: true), fetch it. Two things can still change it afterwards:usersof a customer whose numbers arrive late, and a customer that was suspended at the end of the month and is resumed later (see the warning above). - Match each row of
customersto your own record byexternal_ref, the reference you sent when you created the customer. Fall back onid(cus_…), which never changes.company_idandcompany_namecan be changed, so do not match on them. - A customer you expected and do not find was not live at the end of the last day: look at its
status,suspended_atandcancelled_atwith Get a customer, and mind the UTC month boundary. - A customer you find and did not expect went live before the month ended and was not cancelled or suspended by its last day.
What still needs the portal
Nothing on the Overview page of the portal is missing from the API: the month, the twelve-month trend and the CSV export all have an endpoint. The statement itself, with its amounts, is not in the API.