Concepts
Sellers and attribution
Every customer is credited to the seller who signed it, by your own ID for that person, whether it was made in the portal or over the API.
Who signed what
A seller is a person at your company who signs up customers. Attribution means crediting each customer to the seller who signed it, so the numbers can be read per person.
- A customer made in the portal is credited to the person who made it.
- A customer made over the API is credited to the seller you name with
seller_refin Create a customer:
{
"company_name": "Boulangerie Martin",
"seller_ref": "usr_20503",
"seller_name": "Emma Dubois"
}The customer then carries its seller in every answer:
"seller": { "id": "sel_5", "name": "Emma Dubois", "external_ref": "usr_20503" }Without seller_ref, a customer made over the API has "seller": null. It still counts for your company, but not for a person.
What seller_ref takes
seller_ref (up to 120 characters) is one of two things. Monotree tells them apart by their shape.
| You send | Monotree looks for | When nobody matches |
|---|---|---|
Your own ID for the person, such as usr_20503 |
The seller whose external_ref is exactly that |
A seller is added with that external_ref and no email address. Their name is seller_name, or the reference itself when you send no name |
An email address, such as emma@acme.example |
Your seller with that email address, or the one whose external_ref is that address |
With the sellers:write ability: a seller is added whose external_ref is the address, in lower case, and who has no email address yet. Their name is seller_name, or one made from the address (emma.dubois@… becomes "Emma Dubois"). Without sellers:write: 403 insufficient_ability |
So you never have to add sellers before you create customers. A seller added this way has no login to the portal ("status": "api_only"): their customers are credited to them from the first one, and you can invite them later.
An address in seller_ref is only ever looked up among your own sellers, and it is kept as a reference, not as a sign-in address. The answer is the same whether or not someone else uses that address, and naming an address creates no account with it. To let the person sign in, give them the address with Change a seller and invite them: that call checks the address, and needs admins:write once the seller has customers. New sellers added by an address are limited to 60 an hour per mode (429 rate_limited above that); a reference that is not an address is not counted.
Three more rules:
seller_name(up to 80 characters) only names a seller. It is used when the seller is new, and it replaces the name of a seller who is still called by their reference. It never renames anyone else: use Change a seller for that.- A reference that matches a disabled seller is refused with
422:
{ "error": { "type": "validation_error", "message": "Some fields are missing or invalid.", "fields": { "seller_ref": ["This seller is disabled."] } } }- An email address that cannot be used for a new seller is refused the same way, with
"This email address cannot be used.". The sentence is the same for every reason, and never says whose the address is.
Reading sellers
A seller has Monotree's ID (sel_5). Wherever a path takes that ID, you can use your own reference instead: external_ref: followed by it. A seller added by an email address has no reference, so find them with GET /sellers?email=… and give them one with Change a seller.
curl https://partners.monotree.com/api/v1/sellers/external_ref:usr_20503 \
-H "Authorization: Bearer $MONOTREE_TOKEN"{
"id": "sel_5",
"object": "seller",
"name": "Emma Dubois",
"email": "emma@acme.example",
"role": "seller",
"external_ref": "usr_20503",
"status": "active",
"can_login": true,
"disabled": false,
"two_factor": true,
"passkeys": 0,
"adoption_digest": true,
"live_customers": 11,
"employees": 261,
"signed_this_month": 1,
"invited_at": "2026-03-12T13:28:06Z",
"last_login_at": "2026-11-14T12:41:59Z",
"created_at": "2026-03-12T13:28:06Z",
"updated_at": "2026-11-14T12:41:59Z"
}| Field | Means |
|---|---|
email |
Their email address. null for a seller known only by your reference |
role |
admin or seller, see Roles |
external_ref |
Your own ID for them. null when you never gave one |
status |
See Status |
can_login |
Whether they can sign in to the portal: invited at some time and not disabled. false for a disabled person |
two_factor, passkeys |
How they sign in, see Security and sign-in. Only present when the token has the security:read ability |
adoption_digest |
Whether they get the Monday email about customers that stall |
live_customers |
Their customers that are live or suspended. Drafts, cancelled and deleted customers are left out |
employees |
The employees of those customers, added up |
signed_this_month |
Their customers submitted since the first of this month (UTC) |
invited_at |
When the last invitation was emailed, or null |
last_login_at |
Their last sign-in to the portal, or null. Only present when the token has the security:read ability |
List sellers gives everyone, admins too, newest first by when they were added. It reads with the customers:read ability and filters on:
| Parameter | Gives |
|---|---|
role |
admin or seller |
status |
active, invited, api_only or disabled |
disabled |
true for disabled people only, false to leave them out |
q |
People whose name, email address or reference contains the text |
email |
The person with exactly this email address |
external_ref |
The person with exactly this reference |
updated_since |
People whose updated_at is at or after a time. Signing in does not move it |
Page through it with limit and cursor, as every list.
Status
status |
Means |
|---|---|
active |
Has a password and signs in to the portal |
invited |
Was emailed an invitation and has not chosen a password yet |
api_only |
Known from the API (a seller_ref, or added with "invite": false). Has no login |
disabled |
Can no longer sign in. Their customers stay as they are and stay credited to them |
Roles
| Role | Sees in the portal | Can |
|---|---|---|
admin |
Every customer of your company | Everything a seller can, plus suspend, resume and cancel customers, manage people, API tokens and webhooks, and set up the support desk |
seller |
The customers they signed | Sign up customers, change them and resend their invitations |
Roles decide what a person sees in the portal. They do not limit an API token: a token sees every customer of your company in its mode, and what it may do is set by its abilities.
Adding and inviting
Adding, changing and inviting need a token with the sellers:write ability.
curl -X POST https://partners.monotree.com/api/v1/sellers \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "name": "Inès Roux", "email": "ines@acme.example", "external_ref": "usr_20777" }'The answer (201) is the seller with "status": "invited". name and email are required here. Unless you send "invite": false, the person gets an email with a link to choose a password. The link works once, for 7 days.
An invitation is that email. More about it:
- Invite a seller sends the invitation, or sends it again. An earlier link stops working. It also stops working when the seller's email address is changed.
- A seller known only by a reference has no email address, so there is nowhere to send an invitation and the call is refused with
422. Give them anemailfirst;{ "email": "…", "invite": true }in one Change a seller call does both. - A seller who has chosen a password is refused with
409and the typealready_active. A disabled seller is refused with409and the typeseller_disabled: enable them first. "invite": truein Change a seller does the same as the invite call, and answers the same:409 already_activefor someone who already has a password.
No two people can have the same email address, and no two of your sellers the same external_ref. A person signs in with their email address alone, so an address belongs to one person across the whole portal, not only at your company. An address in use outside your company answers "This email address cannot be used.", which does not say where or by whom; adding sellers with invite: false is limited to 60 an hour so that addresses cannot be tried in bulk. A taken one is refused with 422:
{
"error": {
"type": "validation_error",
"message": "Some fields are missing or invalid.",
"fields": {
"email": ["One of your sellers already has this email address."],
"external_ref": ["The external ref has already been taken."]
}
}
}Changing and disabling
Change a seller changes only the fields you send: name, email, role, external_ref (null removes it), invite, disabled and adoption_digest.
curl -X PATCH https://partners.monotree.com/api/v1/sellers/external_ref:usr_20777 \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "disabled": true }'The answer is the seller with "status": "disabled" and "disabled": true.
{ "disabled": true }signs the person out at once and keeps them out. Their customers do not change and stay credited to them, but a new customer with theirseller_refis refused.{ "disabled": false }lets them back in, as they were.{ "adoption_digest": false }turns the Monday email about stalling customers off for them.
A seller cannot be deleted, over the API or in the portal. Disable the people who have left.
Admins and the admins:write ability
An admin opens everything in the portal, so a token needs more than sellers:write to make or change one. The admins:write ability is needed as well to:
- add a seller with
"role": "admin", or make a seller an admin; - change an admin's email address, role or
disabled; - invite an admin, or reset an admin's two-factor sign-in;
- change the email address, or reset the two-factor sign-in, of anyone who signs in to the portal (
status: active: they have chosen a password), seller or admin. The address is what a person signs in with and where a password reset goes, so a token that could change it and reset the second step could take the account over; - change the email address of someone who is invited (the invitation would follow the new address), or of a seller who has customers;
- invite, for the first time, a seller who already has customers, such as one known from
seller_ref. Whoever accepts the invitation sees those customers in the portal; - change or remove the
external_refof a seller who has customers, or give, change or remove the reference of someone who signs in or is invited. The reference is how your own system names who signed a customer (seller_ref): whoever could move it from one seller onto a login of their choosing would get the customers your system signs from then on. Sending the reference a seller already has changes nothing and needs nothing more.
When the email address of someone who signs in changes, by the API or in the portal, their old address gets an email saying so, they are signed out everywhere, and a password-reset link they asked for stops working.
What sellers:write does alone: add a seller (invited or not, with a reference of their own), give an address or a reference to a seller who has no customers and is not invited yet, invite such a seller, and send an invitation again to the address it went to before. Put plainly, sellers:write lets a token create sellers who get into the portal and see the customers they sign from then on. Give it to an integration you would trust with that.
A call that changes an email address counts against the limit for invitations of that seller (3 an hour), and against 30 address changes an hour for all your sellers together.
An admin's name and adoption_digest change with sellers:write alone. Without the ability the answer is 403:
{ "error": { "type": "insufficient_ability", "message": "This request needs the admins:write ability." } }The last admin stays. Your company always keeps one admin who can sign in (not disabled, with a password). Disabling that admin or making them a seller is refused with 409, for a token and for a person in the portal alike:
{ "error": { "type": "last_admin", "message": "This is the only admin who can sign in. Make someone else an admin first, or nobody could manage your company in the portal." } }Sandbox sellers
Sellers are kept apart per mode, like customers. A sandbox seller (or test seller) is one made with a sandbox token (mpt_test_…). With such a token:
- you see, add and change test sellers only. Your real people are not listed and cannot be changed, disabled, invited or reset: their IDs and references answer
404. seller_refon a sandbox customer makes or matches a test seller.- nobody is invited and no email is sent, whatever
invitesays. A test seller never signs in: the answer has"can_login": false,"status": "api_only"and"invited_at": null. Invite a seller answers200with the seller unchanged. - a test seller may have the email address or reference of a real person. It takes nothing from them.
seller.created,seller.updated,seller.disabledandseller.enabledare sent to your sandbox webhook endpoints.seller.invitedis never sent.- the
last_adminrule does not apply.
Test sellers never show in the portal, and a live token never sees them.
Events
Subscribe a webhook endpoint to hear about changes to sellers, whether they were made in the portal or over the API. data.seller is the whole seller as above; there is no data.customer.
| Event | Sent when |
|---|---|
seller.created |
A seller was added: in the portal, with Add a seller, or by a seller_ref seen for the first time |
seller.updated |
Their name, email address, role or reference was changed by an admin or a token |
seller.disabled |
They were disabled |
seller.enabled |
They were enabled again |
seller.invited |
An invitation was emailed to them. Adding a seller with an invitation sends seller.created, then seller.invited |
{
"id": "evt_01m7d1bq458y75685wfrwttj28",
"object": "event",
"type": "seller.disabled",
"api_version": "1.0.0",
"created_at": "2026-11-14T12:43:48Z",
"sandbox": false,
"actor": { "type": "token", "name": "API · Back office, production" },
"data": {
"seller": { "id": "sel_9", "object": "seller", "name": "Inès Roux", "email": "ines@acme.example", "role": "seller", "external_ref": "usr_20777", "status": "disabled", "disabled": true, "…": "…" }
}
}actor says who did it: "type": "token" with the token's name, or "type": "user" with the name of the admin in the portal.
No event is sent when a person chooses their password (invited becomes active), signs in, or has their two-factor sign-in reset. Read those with List sellers and updated_since, or in the sign-in log.
Seeing it
- The Overview in the portal and Get a month count live customers, employees and signups per seller.
- List customers takes
seller(sel_…, orexternal_ref:and your own ID for the seller) to give one seller's customers. So do the statistics, the statement, the adoption alerts and the sign-in log; a seller that does not exist answers404everywhere. - Each customer's timeline names who did what: a person in the portal,
API · <token name>, or Monotree.
How your people sign in, and what the API shows of it, is in Security and sign-in.