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

  1. The API checks the change and keeps it at once. The answer has the new values.
  2. changes_pending is true, and a customer.updated event lists the fields that changed.
  3. Monotree applies the change to the customer's app, usually within a minute.
  4. changes_pending turns false, and a customer.applied event 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
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
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 }; connected says a key is stored. For a customer without the connection, skello is null. The field is only in the answers and events of a partner connected to Skello: every other partner's customers have no skello field at all, and the reference shows it only to the people of a connected partner.
  • "skello": null removes the connection and the stored key.
  • The field can be sent when the customer is created or in a later PATCH. A change shows as skello in the fields of customer.updated and customer.applied.
  • If the setup stops because of the connection, the customer is failed and provisioning.failure_reason says why. Send the right values with a PATCH, 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.