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_ref in Create a customer:
JSON
{
  "company_name": "Boulangerie Martin",
  "seller_ref": "usr_20503",
  "seller_name": "Emma Dubois"
}

The customer then carries its seller in every answer:

JSON
"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:
JSON
{ "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
curl https://partners.monotree.com/api/v1/sellers/external_ref:usr_20503 \
  -H "Authorization: Bearer $MONOTREE_TOKEN"
JSON
{
  "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
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 an email first; { "email": "…", "invite": true } in one Change a seller call does both.
  • A seller who has chosen a password is refused with 409 and the type already_active. A disabled seller is refused with 409 and the type seller_disabled: enable them first.
  • "invite": true in Change a seller does the same as the invite call, and answers the same: 409 already_active for 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:

JSON
{
  "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
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 their seller_ref is 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_ref of 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:

JSON
{ "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:

JSON
{ "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_ref on a sandbox customer makes or matches a test seller.
  • nobody is invited and no email is sent, whatever invite says. A test seller never signs in: the answer has "can_login": false, "status": "api_only" and "invited_at": null. Invite a seller answers 200 with 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.disabled and seller.enabled are sent to your sandbox webhook endpoints. seller.invited is never sent.
  • the last_admin rule 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
JSON
{
  "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_…, or external_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 answers 404 everywhere.
  • 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.