API reference
Customers
The companies you sign up. A customer is created, set up and live in about a minute. Wherever a path takes a customer's ID (cus_…), you can send external_ref: followed by your own reference instead, such as /customers/external_ref:org_48213.
Base URL https://partners.monotree.com/api/v1
· every call needs a token
Endpoints
get/customers
List customers
post
/customers
Create a customer
get
/customers/duplicates
Find look-alike customers
get
/customers/{customer}
Get a customer
patch
/customers/{customer}
Change a customer
delete
/customers/{customer}
Cancel a customer
post
/customers/{customer}/submit
Submit a draft
post
/customers/{customer}/suspend
Suspend a customer
post
/customers/{customer}/resume
Resume a customer
post
/customers/{customer}/retry
Retry a failed setup
post
/customers/{customer}/admin-invite
Resend the admin invitation
get
/customers/{customer}/events
List a customer's events
List customers
/customers
customers:read Your customers, newest first by when they were created (lists cannot be sorted another way). Deleted customers are left out unless you ask for them with status=deleted. To check a copy on your side, ask for updated_since the time of your last call. Each customer in the list is the whole customer, as Get a customer returns it.
Parameters
limit
integer · query
default 25 · up to 100
cursor
string · query
next_cursor of the page before, for the next page. Send the same filters with it.
status
string · query
draft, provisioning, live, failed, suspended, cancelled or deleted. Several states as a comma list (status=live,suspended) or repeated (status[]=live&status[]=suspended).
updated_since
string · query
updated_at): any change to their settings or state.
created_after
string · query
country
string · query
one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL
seller
string · query
sel_12), or external_ref: followed by your own reference for them (external_ref:usr_20503). The same on every list that takes seller. A seller that does not exist answers 404.
adoption
string · query
stalling: only customers with an open adoption alert (their adoption is not null).
one of stalling
external_ref
string · query
q
string · query
Response · 200 A page of customers.
object
string
has_more
boolean
next_cursor
string, nullable
cursor for the next page.
data
array of objects
Errors
invalid_cursor: the cursor is not one this API gave out.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
validation_error: a field is missing or invalid; fields says which.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl https://partners.monotree.com/api/v1/customers \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/customers', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/customers', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://partners.monotree.com/api/v1/customers",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"object": "list",
"has_more": false,
"next_cursor": "string",
"data": [
{
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"url": "https://boulangeriemartin.monotree.com",
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": [
"fr",
"en"
],
"admin": {
"name": "Claire Martin",
"email": "claire@boulangeriemartin.example",
"phone": null
},
"brand": {
"primary_color": "#b45309",
"secondary_color": null,
"logo_light_url": null,
"logo_dark_url": null
},
"seller": {
"id": "sel_13",
"name": "Emma Dubois",
"external_ref": "usr_20503"
},
"external_ref": "org_48213",
"provisioning": {
"step": null,
"step_label": null,
"steps_done": 6,
"steps_total": 6,
"failure_reason": null
},
"changes_pending": false,
"adoption": null,
"sandbox": false,
"created_at": "2026-11-12T09:41:00Z",
"updated_at": "2026-11-12T09:42:18Z",
"submitted_at": "2026-11-12T09:41:00Z",
"live_at": "2026-11-12T09:42:18Z",
"suspended_at": null,
"cancelled_at": null,
"delete_after": null
}
]
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Create a customer
/customers
customers:write Creates the customer and starts setting it up at once: it is provisioning, then live in about a minute, and
its admin gets an invitation by email. Send draft: true to only save it and submit it later. The
Idempotency-Key header is required, so a retry after a timeout never creates a second customer.
Parameters
Idempotency-Key
required
string · header
409 idempotency_key_taken.
Request body
company_name
required
string
at least 2 characters · at most 80 characters
company_id
required
string
<company_id>.monotree.com) and what its employees type in the app. Lower-case letters and digits only, never a hyphen. Must be free: see Check a company ID.
at least 3 characters · at most 40 characters · matches ^[a-z0-9]+$
country
required
string
one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL
employees
required
integer
from 1 · up to 250
default_language
required
string
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
languages
array of strings
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
admin
required
object
name
required
string
at least 2 characters · at most 80 characters
email
required
string
at most 120 characters
phone
string, nullable
at most 30 characters · matches ^\+?[0-9 ().-]{6,30}$
brand
object
primary_color
string, nullable
#rrggbb.
matches ^#[0-9a-fA-F]{6}$
secondary_color
string, nullable
#rrggbb.
matches ^#[0-9a-fA-F]{6}$
logo_light
object, nullable
format
required
string
one of svg, png
content
required
string
logo_dark
object, nullable
format
required
string
one of svg, png
content
required
string
seller_ref
string, nullable
external_ref) or their email. A reference seen for the first time adds a seller without a login. An email address none of your sellers has adds one too, with the address as their external_ref: that needs the sellers:write ability as well (403 without) and is limited to 60 an hour (429). The answer never depends on whether anyone else uses the address.
at most 120 characters
seller_name
string, nullable
seller_ref is new.
at most 80 characters
external_ref
string, nullable
/, ? or #. Use it to find the customer (?external_ref=) or in place of its ID (/customers/external_ref:org_48213).
at most 120 characters
terms_accepted
required
boolean
draft
boolean
company_name and nothing else: the other required fields, and terms_accepted, may come later.
default false
Response · 201 The customer: `provisioning`, or `draft` when you sent `draft: true`.
id
string
object
string
status
string
draft saved, not submitted · provisioning being set up · live in use · failed setup stopped, see
failure_reason · suspended access paused · cancelled access ended, deleted at delete_after · deleted gone.
one of draft, provisioning, live, failed, suspended, cancelled, deleted
company_name
string
company_id
string, nullable
url
string, nullable
country
string, nullable
one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL
employees
integer, nullable
default_language
string, nullable
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
languages
array of strings
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
admin
object
name and email are null on a draft that has no admin yet. All three are null once the customer is deleted: the admin's name and contact details are removed with it.
name
string, nullable
email
string, nullable
phone
string, nullable
brand
object
primary_color
string, nullable
secondary_color
string, nullable
logo_light_url
string, nullable
logo_dark_url
string, nullable
seller
object, nullable
null for a customer made over the API without a seller_ref.
id
string
name
string
external_ref
string, nullable
external_ref
string, nullable
provisioning
object
step
string, nullable
one of reserve, install, brand, languages, admin, checks
step_label
string, nullable
steps_done
integer
steps_total
integer
failure_reason
string, nullable
status is failed.
changes_pending
boolean
adoption
object, nullable
null otherwise. The same shape wherever a customer carries it. Always in English.
alert
string
reason
string
stale: no numbers for 3 days or more. activation: under 30% of the invited employees have registered. drop: the weekly active rate fell under half of what it was 4 weeks before. inactive: under 20% of the users were active in the last week. See Statistics and adoption for the exact rules.
one of stale, activation, drop, inactive
message
string
flagged_at
string, nullable
sandbox
boolean
created_at
string
updated_at
string, nullable
updated_since filters on.
submitted_at
string, nullable
live_at
string, nullable
suspended_at
string, nullable
cancelled_at
string, nullable
delete_after
string, nullable
cancelled_at. Null for a customer that is not cancelled, and once it is deleted.
Errors
idempotency_key_required: the Idempotency-Key header is missing. invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
company_id_busy or external_ref_busy: another request is taking the same company ID or external_ref right now; try again in a moment. limit_reached: you have 200 drafts in this mode already, or 500 customers in the sandbox that are not cancelled. idempotency_in_progress: a call with the same Idempotency-Key is still running. idempotency_key_taken: the key was used by another of your tokens.
validation_error: a field is missing or invalid; fields says which. idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl -X POST https://partners.monotree.com/api/v1/customers \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": [
"fr",
"en"
],
"admin": {
"name": "Claire Martin",
"email": "claire@boulangeriemartin.example",
"phone": "+33 6 12 34 56 78"
},
"brand": {
"primary_color": "#b45309"
},
"seller_ref": "usr_20503",
"seller_name": "Emma Dubois",
"external_ref": "org_48213",
"terms_accepted": true
}'$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/customers', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
'Idempotency-Key' => bin2hex(random_bytes(16)),
],
'json' => [
'company_name' => 'Boulangerie Martin',
'company_id' => 'boulangeriemartin',
'country' => 'FR',
'employees' => 18,
'default_language' => 'fr',
'languages' => [
'fr',
'en',
],
'admin' => [
'name' => 'Claire Martin',
'email' => 'claire@boulangeriemartin.example',
'phone' => '+33 6 12 34 56 78',
],
'brand' => [
'primary_color' => '#b45309',
],
'seller_ref' => 'usr_20503',
'seller_name' => 'Emma Dubois',
'external_ref' => 'org_48213',
'terms_accepted' => true,
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/customers', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Idempotency-Key': crypto.randomUUID(),
'Content-Type': 'application/json',
},
body: JSON.stringify({
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": [
"fr",
"en"
],
"admin": {
"name": "Claire Martin",
"email": "claire@boulangeriemartin.example",
"phone": "+33 6 12 34 56 78"
},
"brand": {
"primary_color": "#b45309"
},
"seller_ref": "usr_20503",
"seller_name": "Emma Dubois",
"external_ref": "org_48213",
"terms_accepted": true
}),
});
const data = await response.json();import os, uuid
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/customers",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": [
"fr",
"en"
],
"admin": {
"name": "Claire Martin",
"email": "claire@boulangeriemartin.example",
"phone": "+33 6 12 34 56 78"
},
"brand": {
"primary_color": "#b45309"
},
"seller_ref": "usr_20503",
"seller_name": "Emma Dubois",
"external_ref": "org_48213",
"terms_accepted": True
},
)
data = response.json(){
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"url": "https://boulangeriemartin.monotree.com",
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": [
"fr",
"en"
],
"admin": {
"name": "Claire Martin",
"email": "claire@boulangeriemartin.example",
"phone": null
},
"brand": {
"primary_color": "#b45309",
"secondary_color": null,
"logo_light_url": null,
"logo_dark_url": null
},
"seller": {
"id": "sel_13",
"name": "Emma Dubois",
"external_ref": "usr_20503"
},
"external_ref": "org_48213",
"provisioning": {
"step": null,
"step_label": null,
"steps_done": 6,
"steps_total": 6,
"failure_reason": null
},
"changes_pending": false,
"adoption": null,
"sandbox": false,
"created_at": "2026-11-12T09:41:00Z",
"updated_at": "2026-11-12T09:42:18Z",
"submitted_at": "2026-11-12T09:41:00Z",
"live_at": "2026-11-12T09:42:18Z",
"suspended_at": null,
"cancelled_at": null,
"delete_after": null
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Find look-alike customers
/customers/duplicates
customers:read Customers of yours that look like one you are about to create: the same company under a slightly different name (legal forms such as SARL or Ltd, accents and a typo are seen through), or the same admin email. Drafts are included, deleted customers are not. It is a warning to show a person, never a refusal: creating the customer still works. At most three per kind of match. Send company_name, admin_email or both.
Parameters
company_name
string · query
admin_email
string · query
Response · 200 The look-alikes, possibly none. Never more than one page.
object
string
has_more
boolean
next_cursor
string, nullable
cursor for the next page.
data
array of objects
Errors
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
validation_error: a field is missing or invalid; fields says which.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl https://partners.monotree.com/api/v1/customers/duplicates \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/customers/duplicates', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/customers/duplicates', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://partners.monotree.com/api/v1/customers/duplicates",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"object": "list",
"has_more": false,
"next_cursor": "string",
"data": [
{
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer_duplicate",
"company_name": "Boulangerie Martin",
"admin_email": "claire@boulangeriemartin.example",
"status": "live",
"seller": {
"id": "sel_12",
"name": "Emma Dubois",
"external_ref": "usr_20503"
},
"created_at": "2026-11-12T09:41:00Z",
"match": "name"
}
]
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Get a customer
/customers/{customer}
customers:read One customer with its state and, while it is being set up, the step it is on.
Parameters
customer
required
string · path
cus_…), or external_ref: followed by your own reference, such as external_ref:org_48213.
Response · 200 The customer.
id
string
object
string
status
string
draft saved, not submitted · provisioning being set up · live in use · failed setup stopped, see
failure_reason · suspended access paused · cancelled access ended, deleted at delete_after · deleted gone.
one of draft, provisioning, live, failed, suspended, cancelled, deleted
company_name
string
company_id
string, nullable
url
string, nullable
country
string, nullable
one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL
employees
integer, nullable
default_language
string, nullable
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
languages
array of strings
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
admin
object
name and email are null on a draft that has no admin yet. All three are null once the customer is deleted: the admin's name and contact details are removed with it.
name
string, nullable
email
string, nullable
phone
string, nullable
brand
object
primary_color
string, nullable
secondary_color
string, nullable
logo_light_url
string, nullable
logo_dark_url
string, nullable
seller
object, nullable
null for a customer made over the API without a seller_ref.
id
string
name
string
external_ref
string, nullable
external_ref
string, nullable
provisioning
object
step
string, nullable
one of reserve, install, brand, languages, admin, checks
step_label
string, nullable
steps_done
integer
steps_total
integer
failure_reason
string, nullable
status is failed.
changes_pending
boolean
adoption
object, nullable
null otherwise. The same shape wherever a customer carries it. Always in English.
alert
string
reason
string
stale: no numbers for 3 days or more. activation: under 30% of the invited employees have registered. drop: the weekly active rate fell under half of what it was 4 weeks before. inactive: under 20% of the users were active in the last week. See Statistics and adoption for the exact rules.
one of stale, activation, drop, inactive
message
string
flagged_at
string, nullable
sandbox
boolean
created_at
string
updated_at
string, nullable
updated_since filters on.
submitted_at
string, nullable
live_at
string, nullable
suspended_at
string, nullable
cancelled_at
string, nullable
delete_after
string, nullable
cancelled_at. Null for a customer that is not cancelled, and once it is deleted.
Errors
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such object for your company in the token's mode.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8 \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"url": "https://boulangeriemartin.monotree.com",
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": [
"fr",
"en"
],
"admin": {
"name": "Claire Martin",
"email": "claire@boulangeriemartin.example",
"phone": null
},
"brand": {
"primary_color": "#b45309",
"secondary_color": null,
"logo_light_url": null,
"logo_dark_url": null
},
"seller": {
"id": "sel_13",
"name": "Emma Dubois",
"external_ref": "usr_20503"
},
"external_ref": "org_48213",
"provisioning": {
"step": null,
"step_label": null,
"steps_done": 6,
"steps_total": 6,
"failure_reason": null
},
"changes_pending": false,
"adoption": null,
"sandbox": false,
"created_at": "2026-11-12T09:41:00Z",
"updated_at": "2026-11-12T09:42:18Z",
"submitted_at": "2026-11-12T09:41:00Z",
"live_at": "2026-11-12T09:42:18Z",
"suspended_at": null,
"cancelled_at": null,
"delete_after": null
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Change a customer
/customers/{customer}
customers:write Changes the settings of a customer: send only the fields that change. The change is kept at once and Monotree
applies it to the customer's app, usually within a minute; changes_pending is true until then, and a
customer.applied event follows (customer.apply_failed if it could not be applied). The company ID cannot
change once the customer is submitted, except while its setup is failed. An external_ref another customer
of yours already has is refused. A call that changes nothing answers 200 and sends no event.
Parameters
customer
required
string · path
cus_…), or external_ref: followed by your own reference, such as external_ref:org_48213.
Request body
company_name
string
at least 2 characters · at most 80 characters
company_id
string
failed. Refused with 422 otherwise.
at least 3 characters · at most 40 characters · matches ^[a-z0-9]+$
country
string
one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL
employees
integer
from 1 · up to 250
default_language
string
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
languages
array of strings
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
admin
object
name and email together. A new email invites that person.
name
required
string
at least 2 characters · at most 80 characters
email
required
string
at most 120 characters
phone
string, nullable
at most 30 characters · matches ^\+?[0-9 ().-]{6,30}$
brand
object
primary_color
string, nullable
#rrggbb.
matches ^#[0-9a-fA-F]{6}$
secondary_color
string, nullable
#rrggbb.
matches ^#[0-9a-fA-F]{6}$
logo_light
object, nullable
format
required
string
one of svg, png
content
required
string
logo_dark
object, nullable
format
required
string
one of svg, png
content
required
string
external_ref
string, nullable
/, ? or #. Use it to find the customer (?external_ref=) or in place of its ID (/customers/external_ref:org_48213).
at most 120 characters
Response · 200 The changed customer.
id
string
object
string
status
string
draft saved, not submitted · provisioning being set up · live in use · failed setup stopped, see
failure_reason · suspended access paused · cancelled access ended, deleted at delete_after · deleted gone.
one of draft, provisioning, live, failed, suspended, cancelled, deleted
company_name
string
company_id
string, nullable
url
string, nullable
country
string, nullable
one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL
employees
integer, nullable
default_language
string, nullable
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
languages
array of strings
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
admin
object
name and email are null on a draft that has no admin yet. All three are null once the customer is deleted: the admin's name and contact details are removed with it.
name
string, nullable
email
string, nullable
phone
string, nullable
brand
object
primary_color
string, nullable
secondary_color
string, nullable
logo_light_url
string, nullable
logo_dark_url
string, nullable
seller
object, nullable
null for a customer made over the API without a seller_ref.
id
string
name
string
external_ref
string, nullable
external_ref
string, nullable
provisioning
object
step
string, nullable
one of reserve, install, brand, languages, admin, checks
step_label
string, nullable
steps_done
integer
steps_total
integer
failure_reason
string, nullable
status is failed.
changes_pending
boolean
adoption
object, nullable
null otherwise. The same shape wherever a customer carries it. Always in English.
alert
string
reason
string
stale: no numbers for 3 days or more. activation: under 30% of the invited employees have registered. drop: the weekly active rate fell under half of what it was 4 weeks before. inactive: under 20% of the users were active in the last week. See Statistics and adoption for the exact rules.
one of stale, activation, drop, inactive
message
string
flagged_at
string, nullable
sandbox
boolean
created_at
string
updated_at
string, nullable
updated_since filters on.
submitted_at
string, nullable
live_at
string, nullable
suspended_at
string, nullable
cancelled_at
string, nullable
delete_after
string, nullable
cancelled_at. Null for a customer that is not cancelled, and once it is deleted.
Errors
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such object for your company in the token's mode.
customer_closed: a cancelled or deleted customer cannot be changed. company_id_busy: another request is taking the same company ID right now.
validation_error: a field is missing or invalid; fields says which.
rate_limited: a token changed admin.email of this customer more than 3 times in a day (each new address is a new invitation; a draft is not counted), or over the general limit. Wait for the number of seconds in Retry-After.
curl -X PATCH https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8 \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"languages": [
"fr",
"en",
"es"
],
"brand": {
"primary_color": "#9a3412",
"logo_light": {
"format": "svg",
"content": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIC8+"
}
}
}'$client = new GuzzleHttp\Client();
$response = $client->request('PATCH', 'https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
'json' => [
'languages' => [
'fr',
'en',
'es',
],
'brand' => [
'primary_color' => '#9a3412',
'logo_light' => [
'format' => 'svg',
'content' => 'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIC8+',
],
],
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"languages": [
"fr",
"en",
"es"
],
"brand": {
"primary_color": "#9a3412",
"logo_light": {
"format": "svg",
"content": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIC8+"
}
}
}),
});
const data = await response.json();import os
import requests
response = requests.patch(
"https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
json={
"languages": [
"fr",
"en",
"es"
],
"brand": {
"primary_color": "#9a3412",
"logo_light": {
"format": "svg",
"content": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIC8+"
}
}
},
)
data = response.json(){
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"url": "https://boulangeriemartin.monotree.com",
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": [
"fr",
"en"
],
"admin": {
"name": "Claire Martin",
"email": "claire@boulangeriemartin.example",
"phone": null
},
"brand": {
"primary_color": "#b45309",
"secondary_color": null,
"logo_light_url": null,
"logo_dark_url": null
},
"seller": {
"id": "sel_13",
"name": "Emma Dubois",
"external_ref": "usr_20503"
},
"external_ref": "org_48213",
"provisioning": {
"step": null,
"step_label": null,
"steps_done": 6,
"steps_total": 6,
"failure_reason": null
},
"changes_pending": false,
"adoption": null,
"sandbox": false,
"created_at": "2026-11-12T09:41:00Z",
"updated_at": "2026-11-12T09:42:18Z",
"submitted_at": "2026-11-12T09:41:00Z",
"live_at": "2026-11-12T09:42:18Z",
"suspended_at": null,
"cancelled_at": null,
"delete_after": null
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Cancel a customer
/customers/{customer}
customers:write A draft is deleted at once (status: deleted). Any other customer is cancelled: its employees lose access
right away and the company with all its data is deleted after 30 days (delete_after); a customer.deleted
event tells you when. Contact Monotree to undo a cancellation before then. Safe to repeat: for a customer that
is already cancelled or deleted the answer is 200 with the customer, and nothing changes.
Parameters
customer
required
string · path
cus_…), or external_ref: followed by your own reference, such as external_ref:org_48213.
Response · 200 The customer: `cancelled`, or `deleted` when it was a draft.
id
string
object
string
status
string
draft saved, not submitted · provisioning being set up · live in use · failed setup stopped, see
failure_reason · suspended access paused · cancelled access ended, deleted at delete_after · deleted gone.
one of draft, provisioning, live, failed, suspended, cancelled, deleted
company_name
string
company_id
string, nullable
url
string, nullable
country
string, nullable
one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL
employees
integer, nullable
default_language
string, nullable
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
languages
array of strings
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
admin
object
name and email are null on a draft that has no admin yet. All three are null once the customer is deleted: the admin's name and contact details are removed with it.
name
string, nullable
email
string, nullable
phone
string, nullable
brand
object
primary_color
string, nullable
secondary_color
string, nullable
logo_light_url
string, nullable
logo_dark_url
string, nullable
seller
object, nullable
null for a customer made over the API without a seller_ref.
id
string
name
string
external_ref
string, nullable
external_ref
string, nullable
provisioning
object
step
string, nullable
one of reserve, install, brand, languages, admin, checks
step_label
string, nullable
steps_done
integer
steps_total
integer
failure_reason
string, nullable
status is failed.
changes_pending
boolean
adoption
object, nullable
null otherwise. The same shape wherever a customer carries it. Always in English.
alert
string
reason
string
stale: no numbers for 3 days or more. activation: under 30% of the invited employees have registered. drop: the weekly active rate fell under half of what it was 4 weeks before. inactive: under 20% of the users were active in the last week. See Statistics and adoption for the exact rules.
one of stale, activation, drop, inactive
message
string
flagged_at
string, nullable
sandbox
boolean
created_at
string
updated_at
string, nullable
updated_since filters on.
submitted_at
string, nullable
live_at
string, nullable
suspended_at
string, nullable
cancelled_at
string, nullable
delete_after
string, nullable
cancelled_at. Null for a customer that is not cancelled, and once it is deleted.
Errors
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such object for your company in the token's mode.
invalid_state: the customer changed state while the call ran; read it and try again.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl -X DELETE https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8 \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('DELETE', 'https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.delete(
"https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"url": "https://boulangeriemartin.monotree.com",
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": [
"fr",
"en"
],
"admin": {
"name": "Claire Martin",
"email": "claire@boulangeriemartin.example",
"phone": null
},
"brand": {
"primary_color": "#b45309",
"secondary_color": null,
"logo_light_url": null,
"logo_dark_url": null
},
"seller": {
"id": "sel_13",
"name": "Emma Dubois",
"external_ref": "usr_20503"
},
"external_ref": "org_48213",
"provisioning": {
"step": null,
"step_label": null,
"steps_done": 6,
"steps_total": 6,
"failure_reason": null
},
"changes_pending": false,
"adoption": null,
"sandbox": false,
"created_at": "2026-11-12T09:41:00Z",
"updated_at": "2026-11-12T09:42:18Z",
"submitted_at": "2026-11-12T09:41:00Z",
"live_at": "2026-11-12T09:42:18Z",
"suspended_at": null,
"cancelled_at": null,
"delete_after": null
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Submit a draft
/customers/{customer}/submit
customers:write Starts setting up a customer that was created with draft: true. A draft may be unfinished, so this is where everything is checked: the draft must by now hold all that Create a customer requires (company_id, country, employees, default_language, admin.name, admin.email), and the terms must be accepted, when the draft was made or in this call. What is missing is answered with 422 and named in fields, as Create a customer names it; fill it in with Update a customer and submit again.
Parameters
customer
required
string · path
cus_…), or external_ref: followed by your own reference, such as external_ref:org_48213.
Accepts an optional Idempotency-Key header to make a retry safe.
Request body
terms_accepted
boolean
Response · 200 The customer, provisioning.
id
string
object
string
status
string
draft saved, not submitted · provisioning being set up · live in use · failed setup stopped, see
failure_reason · suspended access paused · cancelled access ended, deleted at delete_after · deleted gone.
one of draft, provisioning, live, failed, suspended, cancelled, deleted
company_name
string
company_id
string, nullable
url
string, nullable
country
string, nullable
one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL
employees
integer, nullable
default_language
string, nullable
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
languages
array of strings
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
admin
object
name and email are null on a draft that has no admin yet. All three are null once the customer is deleted: the admin's name and contact details are removed with it.
name
string, nullable
email
string, nullable
phone
string, nullable
brand
object
primary_color
string, nullable
secondary_color
string, nullable
logo_light_url
string, nullable
logo_dark_url
string, nullable
seller
object, nullable
null for a customer made over the API without a seller_ref.
id
string
name
string
external_ref
string, nullable
external_ref
string, nullable
provisioning
object
step
string, nullable
one of reserve, install, brand, languages, admin, checks
step_label
string, nullable
steps_done
integer
steps_total
integer
failure_reason
string, nullable
status is failed.
changes_pending
boolean
adoption
object, nullable
null otherwise. The same shape wherever a customer carries it. Always in English.
alert
string
reason
string
stale: no numbers for 3 days or more. activation: under 30% of the invited employees have registered. drop: the weekly active rate fell under half of what it was 4 weeks before. inactive: under 20% of the users were active in the last week. See Statistics and adoption for the exact rules.
one of stale, activation, drop, inactive
message
string
flagged_at
string, nullable
sandbox
boolean
created_at
string
updated_at
string, nullable
updated_since filters on.
submitted_at
string, nullable
live_at
string, nullable
suspended_at
string, nullable
cancelled_at
string, nullable
delete_after
string, nullable
cancelled_at. Null for a customer that is not cancelled, and once it is deleted.
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such object for your company in the token's mode.
invalid_state: only a draft can be submitted. idempotency_in_progress: a call with the same Idempotency-Key is still running.
validation_error: the draft is not finished, or the terms are not accepted; fields says what is missing. idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl -X POST https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/submit \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"terms_accepted": true
}'$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/submit', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
'json' => [
'terms_accepted' => true,
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/submit', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"terms_accepted": true
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/submit",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
json={
"terms_accepted": True
},
)
data = response.json(){
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"url": "https://boulangeriemartin.monotree.com",
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": [
"fr",
"en"
],
"admin": {
"name": "Claire Martin",
"email": "claire@boulangeriemartin.example",
"phone": null
},
"brand": {
"primary_color": "#b45309",
"secondary_color": null,
"logo_light_url": null,
"logo_dark_url": null
},
"seller": {
"id": "sel_13",
"name": "Emma Dubois",
"external_ref": "usr_20503"
},
"external_ref": "org_48213",
"provisioning": {
"step": null,
"step_label": null,
"steps_done": 6,
"steps_total": 6,
"failure_reason": null
},
"changes_pending": false,
"adoption": null,
"sandbox": false,
"created_at": "2026-11-12T09:41:00Z",
"updated_at": "2026-11-12T09:42:18Z",
"submitted_at": "2026-11-12T09:41:00Z",
"live_at": "2026-11-12T09:42:18Z",
"suspended_at": null,
"cancelled_at": null,
"delete_after": null
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Suspend a customer
/customers/{customer}/suspend
customers:write Pauses a live customer: its employees can no longer sign in, and all data is kept. Resume at any time. Use it, for example, when your customer stops paying you.
Parameters
customer
required
string · path
cus_…), or external_ref: followed by your own reference, such as external_ref:org_48213.
Accepts an optional Idempotency-Key header to make a retry safe.
Request body
reason
string, nullable
customer.suspended event.
at most 200 characters
Response · 200 The suspended customer.
id
string
object
string
status
string
draft saved, not submitted · provisioning being set up · live in use · failed setup stopped, see
failure_reason · suspended access paused · cancelled access ended, deleted at delete_after · deleted gone.
one of draft, provisioning, live, failed, suspended, cancelled, deleted
company_name
string
company_id
string, nullable
url
string, nullable
country
string, nullable
one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL
employees
integer, nullable
default_language
string, nullable
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
languages
array of strings
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
admin
object
name and email are null on a draft that has no admin yet. All three are null once the customer is deleted: the admin's name and contact details are removed with it.
name
string, nullable
email
string, nullable
phone
string, nullable
brand
object
primary_color
string, nullable
secondary_color
string, nullable
logo_light_url
string, nullable
logo_dark_url
string, nullable
seller
object, nullable
null for a customer made over the API without a seller_ref.
id
string
name
string
external_ref
string, nullable
external_ref
string, nullable
provisioning
object
step
string, nullable
one of reserve, install, brand, languages, admin, checks
step_label
string, nullable
steps_done
integer
steps_total
integer
failure_reason
string, nullable
status is failed.
changes_pending
boolean
adoption
object, nullable
null otherwise. The same shape wherever a customer carries it. Always in English.
alert
string
reason
string
stale: no numbers for 3 days or more. activation: under 30% of the invited employees have registered. drop: the weekly active rate fell under half of what it was 4 weeks before. inactive: under 20% of the users were active in the last week. See Statistics and adoption for the exact rules.
one of stale, activation, drop, inactive
message
string
flagged_at
string, nullable
sandbox
boolean
created_at
string
updated_at
string, nullable
updated_since filters on.
submitted_at
string, nullable
live_at
string, nullable
suspended_at
string, nullable
cancelled_at
string, nullable
delete_after
string, nullable
cancelled_at. Null for a customer that is not cancelled, and once it is deleted.
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such object for your company in the token's mode.
invalid_state: only a live customer can be suspended. idempotency_in_progress: a call with the same Idempotency-Key is still running.
validation_error: a field is missing or invalid; fields says which. idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl -X POST https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/suspend \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"reason": "Subscription unpaid"
}'$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/suspend', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
'json' => [
'reason' => 'Subscription unpaid',
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/suspend', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"reason": "Subscription unpaid"
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/suspend",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
json={
"reason": "Subscription unpaid"
},
)
data = response.json(){
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"url": "https://boulangeriemartin.monotree.com",
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": [
"fr",
"en"
],
"admin": {
"name": "Claire Martin",
"email": "claire@boulangeriemartin.example",
"phone": null
},
"brand": {
"primary_color": "#b45309",
"secondary_color": null,
"logo_light_url": null,
"logo_dark_url": null
},
"seller": {
"id": "sel_13",
"name": "Emma Dubois",
"external_ref": "usr_20503"
},
"external_ref": "org_48213",
"provisioning": {
"step": null,
"step_label": null,
"steps_done": 6,
"steps_total": 6,
"failure_reason": null
},
"changes_pending": false,
"adoption": null,
"sandbox": false,
"created_at": "2026-11-12T09:41:00Z",
"updated_at": "2026-11-12T09:42:18Z",
"submitted_at": "2026-11-12T09:41:00Z",
"live_at": "2026-11-12T09:42:18Z",
"suspended_at": null,
"cancelled_at": null,
"delete_after": null
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Resume a customer
/customers/{customer}/resume
customers:write Gives a suspended customer's employees their access back.
Parameters
customer
required
string · path
cus_…), or external_ref: followed by your own reference, such as external_ref:org_48213.
Accepts an optional Idempotency-Key header to make a retry safe.
Response · 200 The live customer.
id
string
object
string
status
string
draft saved, not submitted · provisioning being set up · live in use · failed setup stopped, see
failure_reason · suspended access paused · cancelled access ended, deleted at delete_after · deleted gone.
one of draft, provisioning, live, failed, suspended, cancelled, deleted
company_name
string
company_id
string, nullable
url
string, nullable
country
string, nullable
one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL
employees
integer, nullable
default_language
string, nullable
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
languages
array of strings
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
admin
object
name and email are null on a draft that has no admin yet. All three are null once the customer is deleted: the admin's name and contact details are removed with it.
name
string, nullable
email
string, nullable
phone
string, nullable
brand
object
primary_color
string, nullable
secondary_color
string, nullable
logo_light_url
string, nullable
logo_dark_url
string, nullable
seller
object, nullable
null for a customer made over the API without a seller_ref.
id
string
name
string
external_ref
string, nullable
external_ref
string, nullable
provisioning
object
step
string, nullable
one of reserve, install, brand, languages, admin, checks
step_label
string, nullable
steps_done
integer
steps_total
integer
failure_reason
string, nullable
status is failed.
changes_pending
boolean
adoption
object, nullable
null otherwise. The same shape wherever a customer carries it. Always in English.
alert
string
reason
string
stale: no numbers for 3 days or more. activation: under 30% of the invited employees have registered. drop: the weekly active rate fell under half of what it was 4 weeks before. inactive: under 20% of the users were active in the last week. See Statistics and adoption for the exact rules.
one of stale, activation, drop, inactive
message
string
flagged_at
string, nullable
sandbox
boolean
created_at
string
updated_at
string, nullable
updated_since filters on.
submitted_at
string, nullable
live_at
string, nullable
suspended_at
string, nullable
cancelled_at
string, nullable
delete_after
string, nullable
cancelled_at. Null for a customer that is not cancelled, and once it is deleted.
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such object for your company in the token's mode.
invalid_state: only a suspended customer can be resumed. idempotency_in_progress: a call with the same Idempotency-Key is still running.
idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl -X POST https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/resume \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/resume', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/resume', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/resume",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"url": "https://boulangeriemartin.monotree.com",
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": [
"fr",
"en"
],
"admin": {
"name": "Claire Martin",
"email": "claire@boulangeriemartin.example",
"phone": null
},
"brand": {
"primary_color": "#b45309",
"secondary_color": null,
"logo_light_url": null,
"logo_dark_url": null
},
"seller": {
"id": "sel_13",
"name": "Emma Dubois",
"external_ref": "usr_20503"
},
"external_ref": "org_48213",
"provisioning": {
"step": null,
"step_label": null,
"steps_done": 6,
"steps_total": 6,
"failure_reason": null
},
"changes_pending": false,
"adoption": null,
"sandbox": false,
"created_at": "2026-11-12T09:41:00Z",
"updated_at": "2026-11-12T09:42:18Z",
"submitted_at": "2026-11-12T09:41:00Z",
"live_at": "2026-11-12T09:42:18Z",
"suspended_at": null,
"cancelled_at": null,
"delete_after": null
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Retry a failed setup
/customers/{customer}/retry
customers:write Starts the setup again for a customer whose setup stopped (failed), from the step it stopped on. Fix what failure_reason names first, often with Change a customer.
Parameters
customer
required
string · path
cus_…), or external_ref: followed by your own reference, such as external_ref:org_48213.
Accepts an optional Idempotency-Key header to make a retry safe.
Response · 200 The customer, provisioning.
id
string
object
string
status
string
draft saved, not submitted · provisioning being set up · live in use · failed setup stopped, see
failure_reason · suspended access paused · cancelled access ended, deleted at delete_after · deleted gone.
one of draft, provisioning, live, failed, suspended, cancelled, deleted
company_name
string
company_id
string, nullable
url
string, nullable
country
string, nullable
one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL
employees
integer, nullable
default_language
string, nullable
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
languages
array of strings
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
admin
object
name and email are null on a draft that has no admin yet. All three are null once the customer is deleted: the admin's name and contact details are removed with it.
name
string, nullable
email
string, nullable
phone
string, nullable
brand
object
primary_color
string, nullable
secondary_color
string, nullable
logo_light_url
string, nullable
logo_dark_url
string, nullable
seller
object, nullable
null for a customer made over the API without a seller_ref.
id
string
name
string
external_ref
string, nullable
external_ref
string, nullable
provisioning
object
step
string, nullable
one of reserve, install, brand, languages, admin, checks
step_label
string, nullable
steps_done
integer
steps_total
integer
failure_reason
string, nullable
status is failed.
changes_pending
boolean
adoption
object, nullable
null otherwise. The same shape wherever a customer carries it. Always in English.
alert
string
reason
string
stale: no numbers for 3 days or more. activation: under 30% of the invited employees have registered. drop: the weekly active rate fell under half of what it was 4 weeks before. inactive: under 20% of the users were active in the last week. See Statistics and adoption for the exact rules.
one of stale, activation, drop, inactive
message
string
flagged_at
string, nullable
sandbox
boolean
created_at
string
updated_at
string, nullable
updated_since filters on.
submitted_at
string, nullable
live_at
string, nullable
suspended_at
string, nullable
cancelled_at
string, nullable
delete_after
string, nullable
cancelled_at. Null for a customer that is not cancelled, and once it is deleted.
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such object for your company in the token's mode.
invalid_state: only a customer whose setup failed can be retried. idempotency_in_progress: a call with the same Idempotency-Key is still running.
idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl -X POST https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/retry \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/retry', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/retry', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/retry",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"url": "https://boulangeriemartin.monotree.com",
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": [
"fr",
"en"
],
"admin": {
"name": "Claire Martin",
"email": "claire@boulangeriemartin.example",
"phone": null
},
"brand": {
"primary_color": "#b45309",
"secondary_color": null,
"logo_light_url": null,
"logo_dark_url": null
},
"seller": {
"id": "sel_13",
"name": "Emma Dubois",
"external_ref": "usr_20503"
},
"external_ref": "org_48213",
"provisioning": {
"step": null,
"step_label": null,
"steps_done": 6,
"steps_total": 6,
"failure_reason": null
},
"changes_pending": false,
"adoption": null,
"sandbox": false,
"created_at": "2026-11-12T09:41:00Z",
"updated_at": "2026-11-12T09:42:18Z",
"submitted_at": "2026-11-12T09:41:00Z",
"live_at": "2026-11-12T09:42:18Z",
"suspended_at": null,
"cancelled_at": null,
"delete_after": null
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Resend the admin invitation
/customers/{customer}/admin-invite
customers:write Sends the customer's admin a new invitation email. Only for a live customer.
Parameters
customer
required
string · path
cus_…), or external_ref: followed by your own reference, such as external_ref:org_48213.
Accepts an optional Idempotency-Key header to make a retry safe.
Response · 200 The customer.
id
string
object
string
status
string
draft saved, not submitted · provisioning being set up · live in use · failed setup stopped, see
failure_reason · suspended access paused · cancelled access ended, deleted at delete_after · deleted gone.
one of draft, provisioning, live, failed, suspended, cancelled, deleted
company_name
string
company_id
string, nullable
url
string, nullable
country
string, nullable
one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL
employees
integer, nullable
default_language
string, nullable
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
languages
array of strings
one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl
admin
object
name and email are null on a draft that has no admin yet. All three are null once the customer is deleted: the admin's name and contact details are removed with it.
name
string, nullable
email
string, nullable
phone
string, nullable
brand
object
primary_color
string, nullable
secondary_color
string, nullable
logo_light_url
string, nullable
logo_dark_url
string, nullable
seller
object, nullable
null for a customer made over the API without a seller_ref.
id
string
name
string
external_ref
string, nullable
external_ref
string, nullable
provisioning
object
step
string, nullable
one of reserve, install, brand, languages, admin, checks
step_label
string, nullable
steps_done
integer
steps_total
integer
failure_reason
string, nullable
status is failed.
changes_pending
boolean
adoption
object, nullable
null otherwise. The same shape wherever a customer carries it. Always in English.
alert
string
reason
string
stale: no numbers for 3 days or more. activation: under 30% of the invited employees have registered. drop: the weekly active rate fell under half of what it was 4 weeks before. inactive: under 20% of the users were active in the last week. See Statistics and adoption for the exact rules.
one of stale, activation, drop, inactive
message
string
flagged_at
string, nullable
sandbox
boolean
created_at
string
updated_at
string, nullable
updated_since filters on.
submitted_at
string, nullable
live_at
string, nullable
suspended_at
string, nullable
cancelled_at
string, nullable
delete_after
string, nullable
cancelled_at. Null for a customer that is not cancelled, and once it is deleted.
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such object for your company in the token's mode.
invalid_state: only a live customer has an admin to invite. idempotency_in_progress: a call with the same Idempotency-Key is still running.
idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: more than 1 invitation in 10 minutes for this customer, or over the general limit. Wait for the number of seconds in Retry-After.
curl -X POST https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/admin-invite \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/admin-invite', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/admin-invite', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/admin-invite",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"url": "https://boulangeriemartin.monotree.com",
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": [
"fr",
"en"
],
"admin": {
"name": "Claire Martin",
"email": "claire@boulangeriemartin.example",
"phone": null
},
"brand": {
"primary_color": "#b45309",
"secondary_color": null,
"logo_light_url": null,
"logo_dark_url": null
},
"seller": {
"id": "sel_13",
"name": "Emma Dubois",
"external_ref": "usr_20503"
},
"external_ref": "org_48213",
"provisioning": {
"step": null,
"step_label": null,
"steps_done": 6,
"steps_total": 6,
"failure_reason": null
},
"changes_pending": false,
"adoption": null,
"sandbox": false,
"created_at": "2026-11-12T09:41:00Z",
"updated_at": "2026-11-12T09:42:18Z",
"submitted_at": "2026-11-12T09:41:00Z",
"live_at": "2026-11-12T09:42:18Z",
"suspended_at": null,
"cancelled_at": null,
"delete_after": null
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
List a customer's events
/customers/{customer}/events
customers:read Every event about one customer, with who did what: the same events, in the same shape and with the same filters, as List events with customer. Newest first unless after or order says otherwise. Events are kept for 90 days, and a token only gets the events it may read.
Parameters
customer
required
string · path
cus_…), or external_ref: followed by your own reference, such as external_ref:org_48213.
limit
integer · query
default 25 · up to 100
cursor
string · query
next_cursor of the page before, for the next page. Send the same filters with it.
type
string · query
customer.live. One type per call. A type that does not exist answers 422.
created_after
string · query
after
string · query
order says otherwise. 404 when the event is unknown or older than 90 days: use created_after then.
order
string · query
desc newest first, asc oldest first. Defaults to desc, or to asc when after is sent.
one of asc, desc
Response · 200 A page of events.
object
string
has_more
boolean
next_cursor
string, nullable
cursor for the next page.
data
array of objects
Errors
invalid_cursor: the cursor is not one this API gave out.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such customer, or the event named in after is unknown or older than 90 days.
validation_error: a field is missing or invalid; fields says which.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/events \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/events', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/events', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/events",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"object": "list",
"has_more": false,
"next_cursor": "string",
"data": [
{
"id": "evt_01jcz8wg4h7v3y6n9q2k5m8p1r",
"object": "event",
"type": "customer.live",
"api_version": "1.0.0",
"created_at": "2026-11-12T09:42:18Z",
"sandbox": false,
"actor": {
"type": "system",
"name": "Monotree"
},
"data": {
"customer": {
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"external_ref": "org_48213"
},
"details": {
"url": "https://boulangeriemartin.monotree.com",
"admin_email": "claire@boulangeriemartin.example"
}
}
}
]
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.