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

List customers

get /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

How many to return in a page, 1 to 100.

default 25 · up to 100

cursor

string · query

The next_cursor of the page before, for the next page. Send the same filters with it.

status

string · query

Only customers in this state: 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

Only customers changed at or after this time (their updated_at): any change to their settings or state.

created_after

string · query

Only customers created after this time.

country

string · query

Only customers in this country.

one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL

seller

string · query

Only what belongs to this seller: their ID (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

Only the customer with this reference of your own.

q

string · query

Only customers whose company name, company ID or admin email contains this text.
Response · 200 A page of customers.

object

string

has_more

boolean

Whether there is a page after this one.

next_cursor

string, nullable

Pass as cursor for the next page.

data

array of objects

Errors

400 invalid_cursor: the cursor is not one this API gave out.
401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
422 validation_error: a field is missing or invalid; fields says which.
429 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"
200 · Response
{
    "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.

Sending…

                    

Create a customer

post /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

Required. Any unique string up to 255 characters, such as a UUID. A repeat with the same key and body returns the first answer; with a different body it is refused. Keys are scoped to your partner and mode (live or sandbox), and a kept answer is only given to the token that sent the key: another of your tokens gets 409 idempotency_key_taken.

Request body

company_name required

string

The name employees see.

at least 2 characters · at most 80 characters

company_id required

string

The customer's address (<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

ISO 3166-1 alpha-2.

one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL

employees required

integer

Everyone who will use the app.

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

The languages employees can pick. The default language is always included, also when you leave it out.

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

The invitation goes here.

at most 120 characters

phone

string, nullable

at most 30 characters · matches ^\+?[0-9 ().-]{6,30}$

brand

object

primary_color

string, nullable

The main colour, as #rrggbb.

matches ^#[0-9a-fA-F]{6}$

secondary_color

string, nullable

An accent colour, as #rrggbb.

matches ^#[0-9a-fA-F]{6}$

logo_light

object, nullable

For a light background.

format required

string

one of svg, png

content required

string

The file, base64 encoded. At most 512 KB before encoding. An SVG with a script, an event handler or foreign content is refused; anything else that is not drawing is dropped.

logo_dark

object, nullable

For dark mode.

format required

string

one of svg, png

content required

string

The file, base64 encoded. At most 512 KB before encoding. An SVG with a script, an event handler or foreign content is refused; anything else that is not drawing is dropped.

seller_ref

string, nullable

Who signed the customer: your own reference for the seller (their 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

The seller's name, used when seller_ref is new.

at most 80 characters

external_ref

string, nullable

Your own reference for the customer, such as the ID of the organisation in your system. One customer per reference and mode (deleted customers aside), without /, ? 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

The customer has agreed to the Monotree terms and data processing agreement. A draft may leave it out and send it with Submit a draft.

draft

boolean

Only save it; submit it later with Submit a draft. A draft needs a 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

Null only on a draft that has none yet.

url

string, nullable

Null only on a draft without a company ID.

country

string, nullable

ISO 3166-1 alpha-2.

one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL

employees

integer, nullable

Null only on a draft that has none yet.

default_language

string, nullable

Null only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

languages

array of strings

Empty only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

admin

object

The customer's admin. 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

A link to the stored logo, to show in your own product. Null when there is none.

logo_dark_url

string, nullable

seller

object, nullable

A seller as another object names one: the seller a customer is credited to, a row of the statement, the person of a sign-in. The same three fields everywhere; the whole seller, with the email address, is Get a seller. 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

Where the setup is.

step

string, nullable

The step the setup is on, or stopped on. Null before it starts and once the customer is live. Steps may be added in later versions.

one of reserve, install, brand, languages, admin, checks

step_label

string, nullable

The step in words, in English.

steps_done

integer

steps_total

integer

failure_reason

string, nullable

Why the setup stopped, as a sentence for a person. Set while status is failed.

changes_pending

boolean

A change is saved and on its way to the customer's app.

adoption

object, nullable

The customer's open adoption alert: set while the customer is stalling, null otherwise. The same shape wherever a customer carries it. Always in English.

alert

string

The ID of the adoption alert.

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

The reason as a sentence, with its numbers.

flagged_at

string, nullable

When the alert was first raised.

sandbox

boolean

True for a test customer made with a sandbox token.

created_at

string

updated_at

string, nullable

When its settings or state last changed. What updated_since filters on.

submitted_at

string, nullable

live_at

string, nullable

suspended_at

string, nullable

cancelled_at

string, nullable

delete_after

string, nullable

When a cancelled customer is deleted: 30 days after cancelled_at. Null for a customer that is not cancelled, and once it is deleted.

Errors

400 idempotency_key_required: the Idempotency-Key header is missing. invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
409 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.
422 validation_error: a field is missing or invalid; fields says which. idempotency_key_reused: the Idempotency-Key was used for a different request.
429 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
}'
201 · Response
{
    "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.

Sending…

                    

Find look-alike customers

get /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

The name of the company you are about to create.

admin_email

string · query

The email of its admin.
Response · 200 The look-alikes, possibly none. Never more than one page.

object

string

has_more

boolean

Whether there is a page after this one.

next_cursor

string, nullable

Pass as cursor for the next page.

data

array of objects

Errors

401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
422 validation_error: a field is missing or invalid; fields says which.
429 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"
200 · Response
{
    "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.

Sending…

                    

Get a customer

get /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

The customer's ID (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

Null only on a draft that has none yet.

url

string, nullable

Null only on a draft without a company ID.

country

string, nullable

ISO 3166-1 alpha-2.

one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL

employees

integer, nullable

Null only on a draft that has none yet.

default_language

string, nullable

Null only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

languages

array of strings

Empty only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

admin

object

The customer's admin. 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

A link to the stored logo, to show in your own product. Null when there is none.

logo_dark_url

string, nullable

seller

object, nullable

A seller as another object names one: the seller a customer is credited to, a row of the statement, the person of a sign-in. The same three fields everywhere; the whole seller, with the email address, is Get a seller. 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

Where the setup is.

step

string, nullable

The step the setup is on, or stopped on. Null before it starts and once the customer is live. Steps may be added in later versions.

one of reserve, install, brand, languages, admin, checks

step_label

string, nullable

The step in words, in English.

steps_done

integer

steps_total

integer

failure_reason

string, nullable

Why the setup stopped, as a sentence for a person. Set while status is failed.

changes_pending

boolean

A change is saved and on its way to the customer's app.

adoption

object, nullable

The customer's open adoption alert: set while the customer is stalling, null otherwise. The same shape wherever a customer carries it. Always in English.

alert

string

The ID of the adoption alert.

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

The reason as a sentence, with its numbers.

flagged_at

string, nullable

When the alert was first raised.

sandbox

boolean

True for a test customer made with a sandbox token.

created_at

string

updated_at

string, nullable

When its settings or state last changed. What updated_since filters on.

submitted_at

string, nullable

live_at

string, nullable

suspended_at

string, nullable

cancelled_at

string, nullable

delete_after

string, nullable

When a cancelled customer is deleted: 30 days after cancelled_at. Null for a customer that is not cancelled, and once it is deleted.

Errors

401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
404 not_found: no such object for your company in the token's mode.
429 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"
200 · Response
{
    "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.

Sending…

                    

Change a customer

patch /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

The customer's ID (cus_…), or external_ref: followed by your own reference, such as external_ref:org_48213.

Request body

company_name

string

The name employees see.

at least 2 characters · at most 80 characters

company_id

string

Only before the customer is submitted, or while its setup is failed. Refused with 422 otherwise.

at least 3 characters · at most 40 characters · matches ^[a-z0-9]+$

country

string

ISO 3166-1 alpha-2.

one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL

employees

integer

Everyone who will use the app.

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

The whole list, replacing the one before. It must include the default language.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

admin

object

The whole admin: name and email together. A new email invites that person.

name required

string

at least 2 characters · at most 80 characters

email required

string

The invitation goes here.

at most 120 characters

phone

string, nullable

at most 30 characters · matches ^\+?[0-9 ().-]{6,30}$

brand

object

primary_color

string, nullable

The main colour, as #rrggbb.

matches ^#[0-9a-fA-F]{6}$

secondary_color

string, nullable

An accent colour, as #rrggbb.

matches ^#[0-9a-fA-F]{6}$

logo_light

object, nullable

For a light background.

format required

string

one of svg, png

content required

string

The file, base64 encoded. At most 512 KB before encoding. An SVG with a script, an event handler or foreign content is refused; anything else that is not drawing is dropped.

logo_dark

object, nullable

For dark mode.

format required

string

one of svg, png

content required

string

The file, base64 encoded. At most 512 KB before encoding. An SVG with a script, an event handler or foreign content is refused; anything else that is not drawing is dropped.

external_ref

string, nullable

Your own reference for the customer, such as the ID of the organisation in your system. One customer per reference and mode (deleted customers aside), without /, ? 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

Null only on a draft that has none yet.

url

string, nullable

Null only on a draft without a company ID.

country

string, nullable

ISO 3166-1 alpha-2.

one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL

employees

integer, nullable

Null only on a draft that has none yet.

default_language

string, nullable

Null only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

languages

array of strings

Empty only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

admin

object

The customer's admin. 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

A link to the stored logo, to show in your own product. Null when there is none.

logo_dark_url

string, nullable

seller

object, nullable

A seller as another object names one: the seller a customer is credited to, a row of the statement, the person of a sign-in. The same three fields everywhere; the whole seller, with the email address, is Get a seller. 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

Where the setup is.

step

string, nullable

The step the setup is on, or stopped on. Null before it starts and once the customer is live. Steps may be added in later versions.

one of reserve, install, brand, languages, admin, checks

step_label

string, nullable

The step in words, in English.

steps_done

integer

steps_total

integer

failure_reason

string, nullable

Why the setup stopped, as a sentence for a person. Set while status is failed.

changes_pending

boolean

A change is saved and on its way to the customer's app.

adoption

object, nullable

The customer's open adoption alert: set while the customer is stalling, null otherwise. The same shape wherever a customer carries it. Always in English.

alert

string

The ID of the adoption alert.

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

The reason as a sentence, with its numbers.

flagged_at

string, nullable

When the alert was first raised.

sandbox

boolean

True for a test customer made with a sandbox token.

created_at

string

updated_at

string, nullable

When its settings or state last changed. What updated_since filters on.

submitted_at

string, nullable

live_at

string, nullable

suspended_at

string, nullable

cancelled_at

string, nullable

delete_after

string, nullable

When a cancelled customer is deleted: 30 days after cancelled_at. Null for a customer that is not cancelled, and once it is deleted.

Errors

401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
404 not_found: no such object for your company in the token's mode.
409 customer_closed: a cancelled or deleted customer cannot be changed. company_id_busy: another request is taking the same company ID right now.
422 validation_error: a field is missing or invalid; fields says which.
429 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+"
        }
    }
}'
200 · Response
{
    "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.

Sending…

                    

Cancel a customer

delete /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

The customer's ID (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

Null only on a draft that has none yet.

url

string, nullable

Null only on a draft without a company ID.

country

string, nullable

ISO 3166-1 alpha-2.

one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL

employees

integer, nullable

Null only on a draft that has none yet.

default_language

string, nullable

Null only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

languages

array of strings

Empty only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

admin

object

The customer's admin. 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

A link to the stored logo, to show in your own product. Null when there is none.

logo_dark_url

string, nullable

seller

object, nullable

A seller as another object names one: the seller a customer is credited to, a row of the statement, the person of a sign-in. The same three fields everywhere; the whole seller, with the email address, is Get a seller. 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

Where the setup is.

step

string, nullable

The step the setup is on, or stopped on. Null before it starts and once the customer is live. Steps may be added in later versions.

one of reserve, install, brand, languages, admin, checks

step_label

string, nullable

The step in words, in English.

steps_done

integer

steps_total

integer

failure_reason

string, nullable

Why the setup stopped, as a sentence for a person. Set while status is failed.

changes_pending

boolean

A change is saved and on its way to the customer's app.

adoption

object, nullable

The customer's open adoption alert: set while the customer is stalling, null otherwise. The same shape wherever a customer carries it. Always in English.

alert

string

The ID of the adoption alert.

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

The reason as a sentence, with its numbers.

flagged_at

string, nullable

When the alert was first raised.

sandbox

boolean

True for a test customer made with a sandbox token.

created_at

string

updated_at

string, nullable

When its settings or state last changed. What updated_since filters on.

submitted_at

string, nullable

live_at

string, nullable

suspended_at

string, nullable

cancelled_at

string, nullable

delete_after

string, nullable

When a cancelled customer is deleted: 30 days after cancelled_at. Null for a customer that is not cancelled, and once it is deleted.

Errors

401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
404 not_found: no such object for your company in the token's mode.
409 invalid_state: the customer changed state while the call ran; read it and try again.
429 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"
200 · Response
{
    "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.

Sending…

                    

Submit a draft

post /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

The customer's ID (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

The customer has agreed to the Monotree terms and data processing agreement. Needed when the draft was made without it.
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

Null only on a draft that has none yet.

url

string, nullable

Null only on a draft without a company ID.

country

string, nullable

ISO 3166-1 alpha-2.

one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL

employees

integer, nullable

Null only on a draft that has none yet.

default_language

string, nullable

Null only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

languages

array of strings

Empty only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

admin

object

The customer's admin. 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

A link to the stored logo, to show in your own product. Null when there is none.

logo_dark_url

string, nullable

seller

object, nullable

A seller as another object names one: the seller a customer is credited to, a row of the statement, the person of a sign-in. The same three fields everywhere; the whole seller, with the email address, is Get a seller. 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

Where the setup is.

step

string, nullable

The step the setup is on, or stopped on. Null before it starts and once the customer is live. Steps may be added in later versions.

one of reserve, install, brand, languages, admin, checks

step_label

string, nullable

The step in words, in English.

steps_done

integer

steps_total

integer

failure_reason

string, nullable

Why the setup stopped, as a sentence for a person. Set while status is failed.

changes_pending

boolean

A change is saved and on its way to the customer's app.

adoption

object, nullable

The customer's open adoption alert: set while the customer is stalling, null otherwise. The same shape wherever a customer carries it. Always in English.

alert

string

The ID of the adoption alert.

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

The reason as a sentence, with its numbers.

flagged_at

string, nullable

When the alert was first raised.

sandbox

boolean

True for a test customer made with a sandbox token.

created_at

string

updated_at

string, nullable

When its settings or state last changed. What updated_since filters on.

submitted_at

string, nullable

live_at

string, nullable

suspended_at

string, nullable

cancelled_at

string, nullable

delete_after

string, nullable

When a cancelled customer is deleted: 30 days after cancelled_at. Null for a customer that is not cancelled, and once it is deleted.

Errors

400 invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
404 not_found: no such object for your company in the token's mode.
409 invalid_state: only a draft can be submitted. idempotency_in_progress: a call with the same Idempotency-Key is still running.
422 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.
429 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
}'
200 · Response
{
    "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.

Sending…

                    

Suspend a customer

post /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

The customer's ID (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

Why, in your own words. Kept on the customer's timeline and sent in the 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

Null only on a draft that has none yet.

url

string, nullable

Null only on a draft without a company ID.

country

string, nullable

ISO 3166-1 alpha-2.

one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL

employees

integer, nullable

Null only on a draft that has none yet.

default_language

string, nullable

Null only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

languages

array of strings

Empty only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

admin

object

The customer's admin. 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

A link to the stored logo, to show in your own product. Null when there is none.

logo_dark_url

string, nullable

seller

object, nullable

A seller as another object names one: the seller a customer is credited to, a row of the statement, the person of a sign-in. The same three fields everywhere; the whole seller, with the email address, is Get a seller. 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

Where the setup is.

step

string, nullable

The step the setup is on, or stopped on. Null before it starts and once the customer is live. Steps may be added in later versions.

one of reserve, install, brand, languages, admin, checks

step_label

string, nullable

The step in words, in English.

steps_done

integer

steps_total

integer

failure_reason

string, nullable

Why the setup stopped, as a sentence for a person. Set while status is failed.

changes_pending

boolean

A change is saved and on its way to the customer's app.

adoption

object, nullable

The customer's open adoption alert: set while the customer is stalling, null otherwise. The same shape wherever a customer carries it. Always in English.

alert

string

The ID of the adoption alert.

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

The reason as a sentence, with its numbers.

flagged_at

string, nullable

When the alert was first raised.

sandbox

boolean

True for a test customer made with a sandbox token.

created_at

string

updated_at

string, nullable

When its settings or state last changed. What updated_since filters on.

submitted_at

string, nullable

live_at

string, nullable

suspended_at

string, nullable

cancelled_at

string, nullable

delete_after

string, nullable

When a cancelled customer is deleted: 30 days after cancelled_at. Null for a customer that is not cancelled, and once it is deleted.

Errors

400 invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
404 not_found: no such object for your company in the token's mode.
409 invalid_state: only a live customer can be suspended. idempotency_in_progress: a call with the same Idempotency-Key is still running.
422 validation_error: a field is missing or invalid; fields says which. idempotency_key_reused: the Idempotency-Key was used for a different request.
429 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"
}'
200 · Response
{
    "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.

Sending…

                    

Resume a customer

post /customers/{customer}/resume customers:write

Gives a suspended customer's employees their access back.

Parameters

customer required

string · path

The customer's ID (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

Null only on a draft that has none yet.

url

string, nullable

Null only on a draft without a company ID.

country

string, nullable

ISO 3166-1 alpha-2.

one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL

employees

integer, nullable

Null only on a draft that has none yet.

default_language

string, nullable

Null only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

languages

array of strings

Empty only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

admin

object

The customer's admin. 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

A link to the stored logo, to show in your own product. Null when there is none.

logo_dark_url

string, nullable

seller

object, nullable

A seller as another object names one: the seller a customer is credited to, a row of the statement, the person of a sign-in. The same three fields everywhere; the whole seller, with the email address, is Get a seller. 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

Where the setup is.

step

string, nullable

The step the setup is on, or stopped on. Null before it starts and once the customer is live. Steps may be added in later versions.

one of reserve, install, brand, languages, admin, checks

step_label

string, nullable

The step in words, in English.

steps_done

integer

steps_total

integer

failure_reason

string, nullable

Why the setup stopped, as a sentence for a person. Set while status is failed.

changes_pending

boolean

A change is saved and on its way to the customer's app.

adoption

object, nullable

The customer's open adoption alert: set while the customer is stalling, null otherwise. The same shape wherever a customer carries it. Always in English.

alert

string

The ID of the adoption alert.

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

The reason as a sentence, with its numbers.

flagged_at

string, nullable

When the alert was first raised.

sandbox

boolean

True for a test customer made with a sandbox token.

created_at

string

updated_at

string, nullable

When its settings or state last changed. What updated_since filters on.

submitted_at

string, nullable

live_at

string, nullable

suspended_at

string, nullable

cancelled_at

string, nullable

delete_after

string, nullable

When a cancelled customer is deleted: 30 days after cancelled_at. Null for a customer that is not cancelled, and once it is deleted.

Errors

400 invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
404 not_found: no such object for your company in the token's mode.
409 invalid_state: only a suspended customer can be resumed. idempotency_in_progress: a call with the same Idempotency-Key is still running.
422 idempotency_key_reused: the Idempotency-Key was used for a different request.
429 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"
200 · Response
{
    "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.

Sending…

                    

Retry a failed setup

post /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

The customer's ID (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

Null only on a draft that has none yet.

url

string, nullable

Null only on a draft without a company ID.

country

string, nullable

ISO 3166-1 alpha-2.

one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL

employees

integer, nullable

Null only on a draft that has none yet.

default_language

string, nullable

Null only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

languages

array of strings

Empty only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

admin

object

The customer's admin. 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

A link to the stored logo, to show in your own product. Null when there is none.

logo_dark_url

string, nullable

seller

object, nullable

A seller as another object names one: the seller a customer is credited to, a row of the statement, the person of a sign-in. The same three fields everywhere; the whole seller, with the email address, is Get a seller. 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

Where the setup is.

step

string, nullable

The step the setup is on, or stopped on. Null before it starts and once the customer is live. Steps may be added in later versions.

one of reserve, install, brand, languages, admin, checks

step_label

string, nullable

The step in words, in English.

steps_done

integer

steps_total

integer

failure_reason

string, nullable

Why the setup stopped, as a sentence for a person. Set while status is failed.

changes_pending

boolean

A change is saved and on its way to the customer's app.

adoption

object, nullable

The customer's open adoption alert: set while the customer is stalling, null otherwise. The same shape wherever a customer carries it. Always in English.

alert

string

The ID of the adoption alert.

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

The reason as a sentence, with its numbers.

flagged_at

string, nullable

When the alert was first raised.

sandbox

boolean

True for a test customer made with a sandbox token.

created_at

string

updated_at

string, nullable

When its settings or state last changed. What updated_since filters on.

submitted_at

string, nullable

live_at

string, nullable

suspended_at

string, nullable

cancelled_at

string, nullable

delete_after

string, nullable

When a cancelled customer is deleted: 30 days after cancelled_at. Null for a customer that is not cancelled, and once it is deleted.

Errors

400 invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
404 not_found: no such object for your company in the token's mode.
409 invalid_state: only a customer whose setup failed can be retried. idempotency_in_progress: a call with the same Idempotency-Key is still running.
422 idempotency_key_reused: the Idempotency-Key was used for a different request.
429 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"
200 · Response
{
    "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.

Sending…

                    

Resend the admin invitation

post /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

The customer's ID (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

Null only on a draft that has none yet.

url

string, nullable

Null only on a draft without a company ID.

country

string, nullable

ISO 3166-1 alpha-2.

one of FR, BE, CH, LU, ES, PT, IT, DE, AT, NL, GB, IE, DK, SE, NO, FI, PL

employees

integer, nullable

Null only on a draft that has none yet.

default_language

string, nullable

Null only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

languages

array of strings

Empty only on a draft that has none yet.

one of en, fr, es, it, de, nl, pt, da, sv, no, fi, pl

admin

object

The customer's admin. 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

A link to the stored logo, to show in your own product. Null when there is none.

logo_dark_url

string, nullable

seller

object, nullable

A seller as another object names one: the seller a customer is credited to, a row of the statement, the person of a sign-in. The same three fields everywhere; the whole seller, with the email address, is Get a seller. 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

Where the setup is.

step

string, nullable

The step the setup is on, or stopped on. Null before it starts and once the customer is live. Steps may be added in later versions.

one of reserve, install, brand, languages, admin, checks

step_label

string, nullable

The step in words, in English.

steps_done

integer

steps_total

integer

failure_reason

string, nullable

Why the setup stopped, as a sentence for a person. Set while status is failed.

changes_pending

boolean

A change is saved and on its way to the customer's app.

adoption

object, nullable

The customer's open adoption alert: set while the customer is stalling, null otherwise. The same shape wherever a customer carries it. Always in English.

alert

string

The ID of the adoption alert.

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

The reason as a sentence, with its numbers.

flagged_at

string, nullable

When the alert was first raised.

sandbox

boolean

True for a test customer made with a sandbox token.

created_at

string

updated_at

string, nullable

When its settings or state last changed. What updated_since filters on.

submitted_at

string, nullable

live_at

string, nullable

suspended_at

string, nullable

cancelled_at

string, nullable

delete_after

string, nullable

When a cancelled customer is deleted: 30 days after cancelled_at. Null for a customer that is not cancelled, and once it is deleted.

Errors

400 invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
404 not_found: no such object for your company in the token's mode.
409 invalid_state: only a live customer has an admin to invite. idempotency_in_progress: a call with the same Idempotency-Key is still running.
422 idempotency_key_reused: the Idempotency-Key was used for a different request.
429 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"
200 · Response
{
    "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.

Sending…

                    

List a customer's events

get /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

The customer's ID (cus_…), or external_ref: followed by your own reference, such as external_ref:org_48213.

limit

integer · query

How many to return in a page, 1 to 100.

default 25 · up to 100

cursor

string · query

The next_cursor of the page before, for the next page. Send the same filters with it.

type

string · query

Only events of this type, such as customer.live. One type per call. A type that does not exist answers 422.

created_after

string · query

Only events that happened after this time.

after

string · query

Only events that came after the event with this ID, oldest first unless 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

Whether there is a page after this one.

next_cursor

string, nullable

Pass as cursor for the next page.

data

array of objects

Errors

400 invalid_cursor: the cursor is not one this API gave out.
401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
404 not_found: no such customer, or the event named in after is unknown or older than 90 days.
422 validation_error: a field is missing or invalid; fields says which.
429 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"
200 · Response
{
    "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.

Sending…