There are 2 kinds of licenses (also called subscriptions) in Planhat: Fixed Period and Open Ended.

When deciding which license type to use, try to pick the one that most resembles the customer's commitment to pay rather than the actual payments/cash-flow.

Fixed Period:
Applies either when

A) There is clearly defined start date and end date of the license period

B) There is only a start date, but the customer should (according to contract) pay upfront at least 1 month at a time and this fee is not refundable.

Notice Period in the case of Fixed Period Licenses is the time before the (committed) license end date that the agreement needs to be canceled in order not to automatically renew. Thus only relevant if the license is renewing automatically.

Open Ended:

There is only a start date (though it gets an end-date when marked as lost) and the customer can cancel at any time and only pays for the “exact” period used, where exact could be any unit of time less than a month, typically daily or per hourly precision. Open Ended Licenses typically imply that the customer pays at the end of some period, for example each calendar month, except for the rare case where refunds are regularly used, or if there is a notice period (see below).

For Open Ended Licenses, there is is no defined license period and thus nothing to be automatically renewed. In this case, Notice Period can be used to indicate a certain time period after the moment of cancelation that the customer has still committed to pay. As an example the customer may cancel at any time but still pay for another x days.

Most real world cases should be straight forward, but there are some situations that may cause confusion.

Example 1:

License started 1st of January 2016. The customer can cancel at "any time” but should pay for each started month and two more. So if the contract is canceled on the 2nd of January or on the 30th of January it doesn’t matter, the commitment/license is for the whole of January, February and March. However if the month is crossed and February has started then the whole of April is also committed, and so on.

  • License Start Date (from and including): Jan 01, 2016

  • License End Date (to but not including): Feb 01, 2016

  • MRR: $100

  • Type: Fixed Period

  • AutoRenewal: Yes

  • Notice Period: 2 months

Example 2:

License started 1st of January 2016. The customer can cancel at "any time” and should pay for another 30 days after cancelation. So if the contract is canceled on the 2nd of January or on the 25th of January makes a difference. In the first case the commitment/license is until 2 Feb, but in the second case the commitment/license is until 25 Feb.

  • License Start Date (from and including): Jan 01, 2016

  • License End Date none

  • MRR: $100

  • Type: Open Ended

  • AutoRenewal: [Not Applicable]

  • Notice Period: 30 days


Planhat always assumes the start date to be included in the license period.

For example if you sign a license

From: Jan 1, 2016
To: Jan 31, 2016

It’s assumed the the full day of Jan 1st is included.

When it comes to license end dates, you have three options.

1) Always include end-date

Say you sell a license for January (1 full month) and it’s specified as Jan 1, 2016 - Jan 31, 2016, then your intention is that the license is valid to and Including the full day of the 31st.

2) Never Include end-date

A lot of people prefer a format where the license run to, but Not including the end date. A license for the full month of January would then be signed as Jan 1, 2016 - Feb 1, 2016.

3) Best Guess

Which of the formats above you prefer is a matter of taste, they’re both commonly used. Some times, they are even used interchangeably, some contracts may have been signed Jan 1, 2016 - Jan 31, 2016, while others got signed as Jan 1, 2016 - Feb 1, 2016. If this is the case, Planhat still has you covered buy making a qualified guess of your intention on a per license basis.


Contract lengths in Planhat are calculated using the moment.js diff function. To avoid unintended effects on mrr/total value calculation Planhat will round a any period to the closes number of full months as long as the difference doesn’t exceed 36 hours. So a license from Jan 01 to Jan 31 will be given a length of 1 month, even though 1 day technically is missing. If there is a bigger difference, say a contract running from 2016-01-01 to 2016-01-15, then the exact length will be used.


Sometimes a license renews a few days later than expected resulting in a gap, and sometimes the new period starts a little bit earlier resulting in a small overlap. Technically a gap means you get churn when the first period ends, and then newbiz when the renewed license starts. Similarly if there is an overlap you would get an upgrade entering the overlapping period and then a downgrade.

In practice however this is often not what you want, even if you pull a report with start (or end) date at the overlap/gap. Technically there was a small gap, but for you it was just a renewal. To accommodate for this Planhat can help you stretch or “soft push” licenses in the reports, note this stretch/push wont affect the actual mrr or value.

Basically, if there is a gap, the first license will be stretched so that it ends when the next license start, thus bringing the gap. Similarly, if there is an overlap the “renewed” license will be pushed so that it starts when the preceding license ends. This will apply to all adjacent licenses, regardless of if they were created independently or not. Note that if there is a difference in value, the resulting upgrade/downgrade will be counted on the last of the two dates.


Reports in Planhat only compares the situation at the beginning of the report period, and at the end (per customer).

Let say you have a license from the 15th of december to the 15th of January which is then churned. If you pull a report for January, this will show up a s churn, since at the beginning of the period this customer had a license, but at the end of the period it didn’t. Straight forward.

However, let’s say that the license started 1 jan, and lasted to (and including) 31 st of jan.

Did the customer have a license at the end of the report period?

There’s no definitive answer. Some people prefer to count the churn on January, other will consider it a churn for February.

When pulling the reports in Planaht, you chose which of the two style you prefer and it will apply to all relevant metrics such as churn, up-sell, new-bis, bookings etc.


Renewal Status

Each license have a renewal status [renewalStatus] that can take the values “lost”, “renewed”, and “ongoing”. If no status is given (null) it is considered to be ongoing.

As a rule of thumb, a licenses should always have status “lost” or “renewed” when the renewal date (end date minus notice period) has passed or the contract has been canceled. Licenses that are neither “lost” nor “renewed” when the end date has passed will be considered still active, as such they may affect the customer “renewal date”, overdue license alerts, forecast etc. However they won’t be included in MRR calculations, so they will count as churn/downgrade until a proper status is given.

Open Ended Licenses should have renewal status “ongoing” until they are “lost”. Note that all processed licenses (status “renewed” or “lost”) must have a an end date [toDate], even if it was an Open Ended License until it was lost.

Planhat Status Guess

Normally if you manage licenses via the API, you need to keep track of and update the Renewal Status on your own, which typically means at least a daily update of all licenses ending a specific day. There is however a feature in Planhat that will have the system automatically guess the status for you, if there is a new license starting where an open and overdue license ends, the guess will be that it renewed. If the license is overdue and open but no other license starts close to the end date of the first license then the guess will be that it was lost. In practice this is often enough and somewhat fault tolerant as “lost” vs “renewed” is mainly a flag. Churn, MRR and other metrics do not depend on the Renewal Status of the licenses.

Start and End Dates

It’s important to understand how Planhat works with dates, please See above.

MRR vs Value

All Fixed Period Licenses will have both a value (total value for the period) and an MRR. When adding a license however you only need only one of the two. If both are provided then the MRR will be ignored and instead calculated by Planhat. The MRR is calculated as the total value divided by the license length in months (number of months between start and end date). The length is calculated using the diff method of moment.js (http://www.moment.js) but always rounded to the nearest full number of months if the deviation from such a number is less than 5% or about 36 hours.

External Id

You can add an external id [externalId] to any license via the API. It’s a convenience variable if you need to map licenses in Planhat against your own ids.


When a license is renewed (manually or automatically) in Planhat the new license will get a link back to the original license in the form of a variable Parent Id [parent]. Parent is the string representation of the Planhat License Id ("_id”) of the ultimate parent license. Setting this will allow for a better visualisation and overview in Planhat but doesn’t have any other impact at this point.

Did this answer your question?