API reference
Events
Every event your webhook endpoints were sent, or would have been sent, kept for 90 days. Read them to catch up after your server was down, or to start a new system from what already happened.
Base URL https://partners.monotree.com/api/v1
· every call needs a token
List events
/events
customers:read The events of the token's mode (live or sandbox), exactly as their webhooks carried them, whether or not an
endpoint was listening. Newest first by default. To catch up, send after with the id of the last event
you handled: the events that came after it are returned oldest first, so you can handle them in order and go
on with next_cursor until has_more is false. Events are kept for 90 days. Test events (ping) are not
in this list. A token only gets the events it may read: besides customers:read, support.* events
need the support:read ability, webhook_endpoint.* events webhooks:manage and security.* events
security:read (no security.* event is sent yet). Events the token may not read are left out of the
list, and answer 404 when asked for by ID.
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.
type
string · query
customer.live. One type per call. A type that does not exist answers 422.
customer
string · query
external_ref: followed by your own reference.
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: the event named in after is unknown or older than 90 days, or there is no customer as named in customer.
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/events \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/events', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/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/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.
Get an event
/events/{event}
customers:read One event by its id, the one in the webhook body and the Monotree-Event-Id header. An event the token may not read (see List events) answers 404.
Parameters
event
required
string · path
Response · 200 The event.
id
string
Monotree-Event-Id header. Keep it to skip repeats.
object
string
type
string
api_version
string
data is written in; also in the Monotree-Api-Version header.
created_at
string
sandbox
boolean
actor
object, nullable
user), an API token (token, named API · <token name>) or Monotree itself (system). On support events also the assistant (assistant), and on support.message.received the person at the customer who wrote (customer).
type
string
one of user, token, system, assistant, customer
name
string
data
object
customer (the whole customer right after the event) and details. For a seller event: seller, always without two_factor, passkeys and last_login_at. The Event types guide says what each type carries.
Errors
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such event, or it is older than 90 days.
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/events/evt_01jcz8wg4h7v3y6n9q2k5m8p1r \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/events/evt_01jcz8wg4h7v3y6n9q2k5m8p1r', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/events/evt_01jcz8wg4h7v3y6n9q2k5m8p1r', {
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/events/evt_01jcz8wg4h7v3y6n9q2k5m8p1r",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"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.