Concepts

The customer lifecycle

The states a customer goes through, what each means for its employees, and what you can do in it.

The states

status Means Employees You can
draft Saved, not submitted. Nothing is set up. No access change, submit, delete (cancel)
provisioning Monotree is setting the company up, usually about a minute. No access yet change (all but the company ID), cancel
live In use. The admin has an invitation. Sign in change (all but the company ID), suspend, cancel, resend the invite
failed The setup stopped. provisioning.failure_reason says why. No access change (the company ID too), retry, cancel
suspended Access paused, for example while your customer has not paid you. Cannot sign in; data kept change, resume, cancel
cancelled Access ended. Deleted once delete_after has passed, 30 days later. Cannot sign in ask Monotree to undo
deleted The company and its data are gone. – –
Text
draft ──submit──▶ provisioning ──▶ live ◀──resume── suspended
                       │             │ ╲──suspend──▶
                       ▼             ▼
                    failed ──retry──▶ provisioning
   any state ──cancel──▶ cancelled ──30 days──▶ deleted

A customer is created provisioning, or draft when you send draft: true. A draft is a sign-up that is not finished: it needs only a company_name, so its company_id, url, country, employees, default_language, admin.name and admin.email can be null and its languages empty. Submitting it checks that everything is there and that the terms are accepted (422 with the missing fields otherwise); from provisioning on a customer always has them all. Each call answers 409 invalid_state when the customer is not in a state it works from:

Call Works from Leads to
Submit a draft draft provisioning
Suspend live suspended
Resume suspended live
Retry a failed setup failed provisioning
Resend the admin invitation live live
Cancel (DELETE) draft deleted, at once
provisioning, live, failed, suspended cancelled, then deleted after 30 days
cancelled, deleted no change; answers 200
Change (PATCH) every state but cancelled and deleted (409 customer_closed) the same state

Monotree itself moves a customer from provisioning to live or failed, and from cancelled to deleted.

Setup steps

Provisioning is Monotree setting the company up. While a customer is provisioning, provisioning.step names the step it is on and steps_done counts the ones behind it. Each finished step sends a customer.step event: its details.step is the step that finished, and the customer in it is already on the next one.

step What happens
reserve A place is reserved for the company on Monotree's platform
install The company is set up with its name and country
brand The logo and colours are applied
languages The languages are switched on
admin The admin is created and invited by email
checks Final checks that everything answers

When a setup fails

A customer in failed has a provisioning.failure_reason written for a person, for example The company could not be set up. Monotree has been alerted and will look at it. The same sentence is in the customer.failed event, and Monotree is alerted as well. Fix what the reason names, often with a PATCH, then call Retry a failed setup: the setup goes on from the step that stopped, and nothing done before that step is lost. A failed customer is the only submitted one whose company ID can still change, as the ID can be what the setup stopped on.

New steps may be added later: treat a step you do not know as one more step.

Suspending and cancelling

  • Suspend when access should pause but the customer may come back. Their data and settings stay; resume gives everything back as it was.
  • Cancel when the customer leaves. Access ends at once, and the company with all its data is deleted after 30 days. Until then Monotree can undo it on request. A draft is deleted straight away. A customer can be cancelled while it is still provisioning: the setup is not finished and it never goes live.

The deletion is not at the stroke of delete_after: once a day, at 03:00 UTC, Monotree takes the customers whose 30 days are over and deletes them. When it is done the customer's status is deleted and a customer.deleted event is sent. Cancelling a customer that is already cancelled or deleted changes nothing and answers 200 with the customer, so a DELETE is safe to repeat.

What deletion removes

When a customer becomes deleted (a draft at once, any other customer when its 30 days are over), the portal removes what it holds about the customer's people and keeps what the statement needs:

Removed Kept
The admin's name, email address and phone: admin is { "name": null, "email": null, "phone": null } from then on The customer itself: id, company_name, country, employees, external_ref, seller and its dates
Its support threads, with their messages, notes, drafts and files, and the people who wrote Its daily numbers and adoption alerts, which hold no names
The text of its escalations to Monotree (description) The escalations themselves: title, category, status
Email addresses inside its events: details.email and details.admin_email are gone, and data.customer.admin is nulls, in List events and in the delivery log The events of its timeline: what happened and when
Its support.* events and their deliveries, which held what was written
Its logos and, where there was one, the key of its scheduling integration

The company ID is free to use again. The customer.deleted event already has admin as nulls. Your own system may hold copies of what the events told it: customer.deleted is the moment to remove them.

Two calls at the same moment cannot both act: of two submits (or suspends, resumes, retries) only one goes through, and the other gets 409 invalid_state.

The monthly statement says how suspended and cancelled customers are counted.