Concepts
Changing a customer
Rename a customer, add languages, swap its logo or change its admin, in the portal or with one PATCH.
What can change
| Field | A draft | Once submitted |
|---|---|---|
company_name |
yes | yes |
company_id |
yes | no: Monotree reserves it as the setup starts, and it becomes the customer's address and what its employees type in the app. Only a customer whose setup failed can still change it |
country, employees |
yes | yes |
default_language, languages |
yes | yes |
admin |
yes | yes: the new admin is invited |
brand (colours and logos) |
yes | yes |
external_ref |
yes | yes |
The seller a customer is credited to (seller_ref) is set when the customer is created and cannot be changed afterwards. terms_accepted and draft belong to creating a customer too: sending any of the three in a PATCH answers 422. (A draft made without terms_accepted sends it with Submit a draft.)
A draft may be unfinished: on a draft, null also clears company_id, country, employees, default_language and the admin's name and email. Once a customer is submitted these always hold a value.
A cancelled or deleted customer cannot be changed (409 customer_closed).
Feature switches, data and users inside the customer's Monotree are managed by the customer's admin in Monotree itself, not here.
Sending a change
Send only what changes. null clears an optional field. Lists and objects are replaced as a whole: languages is the full list (and must include the default language), and admin needs name and email together.
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": { "secondary_color": null } }'How a change reaches the app
- The API checks the change and keeps it at once. The answer has the new values.
changes_pendingistrue, and acustomer.updatedevent lists the fields that changed.- Monotree applies the change to the customer's app, usually within a minute.
changes_pendingturnsfalse, and acustomer.appliedevent follows.
If Monotree cannot apply the change, a customer.apply_failed event says why. What you sent stays stored, changes_pending turns false, and Monotree looks at it.
A PATCH that changes nothing answers 200 with the customer and sends no event. A draft has no app yet, so changing a draft sends customer.updated only.
Employees see a new logo or colour the next time they open the app.
A change made while the customer is still provisioning is not lost. If the setup has not started on Monotree's side yet, the change is simply part of it: there is no customer.applied and changes_pending stays false. If the setup is already running, the change waits (changes_pending is true) and is applied right after the customer goes live, with its own customer.applied. The same goes for a change made while the setup is failed: it is applied once a retry has brought the customer live.
Your own reference
external_ref is your own name for the customer, such as the ID of the organisation in your system. One customer per reference: a reference that another customer of yours has (in the same mode, deleted customers aside) is refused with 422. It may not contain /, ? or #.
Because it names one customer, you can use it wherever a path takes a customer's ID, with external_ref: in front:
curl https://partners.monotree.com/api/v1/customers/external_ref:org_48213 \
-H "Authorization: Bearer $MONOTREE_TOKEN"That works for every call on a customer (GET, PATCH, DELETE, /suspend, /events, /statistics, …) and for the customer filter of other lists, so your system never has to store Monotree's cus_… ID. A deleted customer is no longer found by its reference, and its reference is free to use again.
Sellers have an external_ref of the same kind: see Sellers and attribution.
Keeping a copy in step
Webhooks tell you about changes as they happen. To check your copy, or to build it, List customers takes updated_since: every customer whose settings or state changed at or after that time (updated_at). Other filters: status (several, as status=live,suspended), country, seller (sel_… or external_ref:<your reference>), external_ref, created_after, adoption=stalling and q. Lists are always newest first. Run everything from your own system shows how webhooks, events and this filter work together.
Before creating a customer, Find look-alike customers tells you whether you already have one with nearly the same name or the same admin email, as the portal warns a seller.
Changing the admin
Sending a new admin.email invites that person as admin. The previous admin keeps their account in Monotree; the customer's own admins decide who stays. To send the same admin a new invitation, use Resend the admin invitation.
Skello connection (only for partners connected to Skello)
Skello is a staff scheduling product. For a partner connected to it, a customer can carry its own Skello credentials, and Monotree then imports the customer's employees from Skello.
curl -X PATCH https://partners.monotree.com/api/v1/customers/external_ref:org_48213 \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "skello": { "organisation_id": "org_7f3a9c", "api_key": "<the customer'\''s Skello API key>" } }'| Field | |
|---|---|
skello.organisation_id |
The customer's organisation ID at Skello. Up to 64 letters, digits, hyphens and underscores. Required whenever skello is sent. |
skello.api_key |
The customer's Skello API key, 16 to 200 characters. Required the first time; left out later, the stored key is kept. It is stored encrypted and never returned. |
- A customer answers with
skello: { "organisation_id": "org_7f3a9c", "connected": true };connectedsays a key is stored. For a customer without the connection,skelloisnull. The field is only in the answers and events of a partner connected to Skello: every other partner's customers have noskellofield at all, and the reference shows it only to the people of a connected partner. "skello": nullremoves the connection and the stored key.- The field can be sent when the customer is created or in a later
PATCH. A change shows asskelloin thefieldsofcustomer.updatedandcustomer.applied. - If the setup stops because of the connection, the customer is
failedandprovisioning.failure_reasonsays why. Send the right values with aPATCH, then retry.
For a partner that is not connected to Skello the field is refused: sending skello with a value answers 422 with the error type validation_error, and fields.skello says the connection is not switched on for your account. "skello": null is accepted and changes nothing.