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
curl "https://partners.monotree.com/api/v1/overview?month=2026-10" \
  -H "Authorization: Bearer $MONOTREE_TOKEN"
JSON
{
  "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
  • month is YYYY-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) answers 422 with the error type validation_error; the message names the months you can ask for.
  • seller= narrows the whole answer to one seller's customers: sel_…, or external_ref: and your own ID for the seller. An unknown seller answers 404.
  • 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
curl "https://partners.monotree.com/api/v1/overview/months" \
  -H "Authorization: Bearer $MONOTREE_TOKEN"
JSON
{
  "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_customers of a month is the same number as in that month's overview.
  • The list is not paged, so it has no has_more or next_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
curl "https://partners.monotree.com/api/v1/overview?month=2026-10&format=csv" \
  -H "Authorization: Bearer $MONOTREE_TOKEN" -o monotree-2026-10.csv
Text
"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,4

The 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-8 and is named monotree-2026-10.csv. It starts with a byte order mark (the three bytes EF 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

  1. Once a month is over (complete: true), fetch it. Two things can still change it afterwards: users of 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).
  2. Match each row of customers to your own record by external_ref, the reference you sent when you created the customer. Fall back on id (cus_…), which never changes. company_id and company_name can be changed, so do not match on them.
  3. A customer you expected and do not find was not live at the end of the last day: look at its status, suspended_at and cancelled_at with Get a customer, and mind the UTC month boundary.
  4. 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.