Developers
Developers
License
Licenses represent your customers' subscriptions to your service and are the base for MRR (or ARR) calculations and most revenue reports. For non-recurring revenue, please see the Sale (NRR) object. There are many ways to get license data into Planhat including incoming webhooks and CRM integrations. In some cases though, you just want to handle it yourself over the API, for example if the main source of license data is your own system.
Licenses in Planhat can be fixed period with a defined start and end date. Or they can be non-fixed period (sometimes called open-ended or evergreen). Open-ended licenses initially don't have a specified end date since the customer may cancel at any time; once the license is churned/lost also non-fixed period licenses can have an end date.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
product | string | Name of the license product. Not required but highly recommended. Even if you only have one product we suggest adding it as "License Fee" or "Subscription". | |
_currency | Yes | string | The currency code, for example "USD". There is a "soft" mapping to the id’s in your list of currencies. Technically we accept any string but we recommend using standard currency codes as Ids. Since the mapping is soft you can add licenses with a currency code not yet available in your list of currencies. |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The license id in your own system. | |
sourceId | string | The license id from an integration (Sales Force, Hubspot, etc). | |
fromDate | Yes | string | Start of the license period (ISO format). |
toDate | string | End of the license period (ISO format). | |
fixedPeriod | boolean | Boolean to indicate if this is an ongoing license (no defined end date) or license with a fixed term. Non fixed-term licenses require an mrr value specified, whereas fixed-term licenses specify the value over the whole period. Defaults to false. | |
mrr | number | Monthly license value (required if fixedPeriod is false). | |
arr | number | Annual license value. | |
renewalMrr | number | Renewal MRR. | |
renewalArr | number | Renewal ARR. | |
fcNewMrr | number | Monthly value forecast. | |
fcNewArr | number | Annual value forecast. | |
fcNewMrrOptimistic | number | Optimistic monthly value forecast. | |
fcNewArrOptimistic | number | Optimistic annual value forecast. | |
fcNewMrrPessimistic | number | Pessimistic monthly value forecast. | |
fcNewArrPessimistic | number | Pessimistic annual value forecast. | |
value | Yes | number | The total license value for the whole subscription period, must be positive (required if fixedPeriod is true and no mrr value). |
renewalStatus | string | Can take one of the following values: 'ongoing', 'renewed', 'lost'. | |
renewalPeriod | integer | Defines the length of the next license period if the subscription should be renewed. Defaults to 1, which would mean the license renews with a new 1-month period, regardless of the length of the current license period. If the renewalPeriod is not set, it will be assumed that the contract renews on the same period as previous. If the license isn’t set to autorenew the renewalPeriod will only serve as guidance for the manual input. | |
renewalDate | string | ISO date when license will be renewed. (Autogenerated). | |
renewalDaysFromNow | integer | Number of days till the next renewal. (Autogenerated). | |
isOverdue | boolean | Flag the license as overdue. (Autogenerated). | |
autoRenews | boolean | If set to true Planhat can automatically renew the subscription for you once the notice period is passed. Necessary for noticePeriod and noticeUnit to be autogenerated. Defaults to false. | |
noticePeriod | integer | Number of days/weeks/months before subscription ends that the license would have to be canceled not to automatically renew. Only makes sense if autoRenews is set to true. Defaults to 0. (Autogenerated). | |
noticeUnit | string | Unit for the noticePeriod, could be days/weeks/months. (Autogenerated). | |
renewalUnit | string | Unit for the noticePeriod, could be day/week/month. Defaults to month. | |
parent | string | Planhat ID of the ultimate parent license. | |
invoicesGenerated | boolean | Set to true for the invoices to not be autogenerated for the license upon creation. Default: false. | |
invoiceMuted | boolean | Set to true to disable the invoices creation when license renewal. Default: false. | |
invoiceCycleInterval | integer | Defines the custom cycle interval. (Autogenerated). | |
invoiceCycle | string | Cycle of the invoice. Could be one of: monthly, quarterly, yearly, semiAnnual, once or custom. (Autogenerated). | |
toDateIncluded | boolean | Set to true if the license has toDate. (Autogenerated). | |
length | number | Internal system field. (Autogenerated). | |
custom | object | A flexible object with custom data. |
Licenses represent your customers' subscriptions to your service and are the base for MRR (or ARR) calculations and most revenue reports. For non-recurring revenue, please see the Sale (NRR) object. There are many ways to get license data into Planhat including incoming webhooks and CRM integrations. In some cases though, you just want to handle it yourself over the API, for example if the main source of license data is your own system.
Licenses in Planhat can be fixed period with a defined start and end date. Or they can be non-fixed period (sometimes called open-ended or evergreen). Open-ended licenses initially don't have a specified end date since the customer may cancel at any time; once the license is churned/lost also non-fixed period licenses can have an end date.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
product | string | Name of the license product. Not required but highly recommended. Even if you only have one product we suggest adding it as "License Fee" or "Subscription". | |
_currency | Yes | string | The currency code, for example "USD". There is a "soft" mapping to the id’s in your list of currencies. Technically we accept any string but we recommend using standard currency codes as Ids. Since the mapping is soft you can add licenses with a currency code not yet available in your list of currencies. |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The license id in your own system. | |
sourceId | string | The license id from an integration (Sales Force, Hubspot, etc). | |
fromDate | Yes | string | Start of the license period (ISO format). |
toDate | string | End of the license period (ISO format). | |
fixedPeriod | boolean | Boolean to indicate if this is an ongoing license (no defined end date) or license with a fixed term. Non fixed-term licenses require an mrr value specified, whereas fixed-term licenses specify the value over the whole period. Defaults to false. | |
mrr | number | Monthly license value (required if fixedPeriod is false). | |
arr | number | Annual license value. | |
renewalMrr | number | Renewal MRR. | |
renewalArr | number | Renewal ARR. | |
fcNewMrr | number | Monthly value forecast. | |
fcNewArr | number | Annual value forecast. | |
fcNewMrrOptimistic | number | Optimistic monthly value forecast. | |
fcNewArrOptimistic | number | Optimistic annual value forecast. | |
fcNewMrrPessimistic | number | Pessimistic monthly value forecast. | |
fcNewArrPessimistic | number | Pessimistic annual value forecast. | |
value | Yes | number | The total license value for the whole subscription period, must be positive (required if fixedPeriod is true and no mrr value). |
renewalStatus | string | Can take one of the following values: 'ongoing', 'renewed', 'lost'. | |
renewalPeriod | integer | Defines the length of the next license period if the subscription should be renewed. Defaults to 1, which would mean the license renews with a new 1-month period, regardless of the length of the current license period. If the renewalPeriod is not set, it will be assumed that the contract renews on the same period as previous. If the license isn’t set to autorenew the renewalPeriod will only serve as guidance for the manual input. | |
renewalDate | string | ISO date when license will be renewed. (Autogenerated). | |
renewalDaysFromNow | integer | Number of days till the next renewal. (Autogenerated). | |
isOverdue | boolean | Flag the license as overdue. (Autogenerated). | |
autoRenews | boolean | If set to true Planhat can automatically renew the subscription for you once the notice period is passed. Necessary for noticePeriod and noticeUnit to be autogenerated. Defaults to false. | |
noticePeriod | integer | Number of days/weeks/months before subscription ends that the license would have to be canceled not to automatically renew. Only makes sense if autoRenews is set to true. Defaults to 0. (Autogenerated). | |
noticeUnit | string | Unit for the noticePeriod, could be days/weeks/months. (Autogenerated). | |
renewalUnit | string | Unit for the noticePeriod, could be day/week/month. Defaults to month. | |
parent | string | Planhat ID of the ultimate parent license. | |
invoicesGenerated | boolean | Set to true for the invoices to not be autogenerated for the license upon creation. Default: false. | |
invoiceMuted | boolean | Set to true to disable the invoices creation when license renewal. Default: false. | |
invoiceCycleInterval | integer | Defines the custom cycle interval. (Autogenerated). | |
invoiceCycle | string | Cycle of the invoice. Could be one of: monthly, quarterly, yearly, semiAnnual, once or custom. (Autogenerated). | |
toDateIncluded | boolean | Set to true if the license has toDate. (Autogenerated). | |
length | number | Internal system field. (Autogenerated). | |
custom | object | A flexible object with custom data. |
Licenses represent your customers' subscriptions to your service and are the base for MRR (or ARR) calculations and most revenue reports. For non-recurring revenue, please see the Sale (NRR) object. There are many ways to get license data into Planhat including incoming webhooks and CRM integrations. In some cases though, you just want to handle it yourself over the API, for example if the main source of license data is your own system.
Licenses in Planhat can be fixed period with a defined start and end date. Or they can be non-fixed period (sometimes called open-ended or evergreen). Open-ended licenses initially don't have a specified end date since the customer may cancel at any time; once the license is churned/lost also non-fixed period licenses can have an end date.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
product | string | Name of the license product. Not required but highly recommended. Even if you only have one product we suggest adding it as "License Fee" or "Subscription". | |
_currency | Yes | string | The currency code, for example "USD". There is a "soft" mapping to the id’s in your list of currencies. Technically we accept any string but we recommend using standard currency codes as Ids. Since the mapping is soft you can add licenses with a currency code not yet available in your list of currencies. |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The license id in your own system. | |
sourceId | string | The license id from an integration (Sales Force, Hubspot, etc). | |
fromDate | Yes | string | Start of the license period (ISO format). |
toDate | string | End of the license period (ISO format). | |
fixedPeriod | boolean | Boolean to indicate if this is an ongoing license (no defined end date) or license with a fixed term. Non fixed-term licenses require an mrr value specified, whereas fixed-term licenses specify the value over the whole period. Defaults to false. | |
mrr | number | Monthly license value (required if fixedPeriod is false). | |
arr | number | Annual license value. | |
renewalMrr | number | Renewal MRR. | |
renewalArr | number | Renewal ARR. | |
fcNewMrr | number | Monthly value forecast. | |
fcNewArr | number | Annual value forecast. | |
fcNewMrrOptimistic | number | Optimistic monthly value forecast. | |
fcNewArrOptimistic | number | Optimistic annual value forecast. | |
fcNewMrrPessimistic | number | Pessimistic monthly value forecast. | |
fcNewArrPessimistic | number | Pessimistic annual value forecast. | |
value | Yes | number | The total license value for the whole subscription period, must be positive (required if fixedPeriod is true and no mrr value). |
renewalStatus | string | Can take one of the following values: 'ongoing', 'renewed', 'lost'. | |
renewalPeriod | integer | Defines the length of the next license period if the subscription should be renewed. Defaults to 1, which would mean the license renews with a new 1-month period, regardless of the length of the current license period. If the renewalPeriod is not set, it will be assumed that the contract renews on the same period as previous. If the license isn’t set to autorenew the renewalPeriod will only serve as guidance for the manual input. | |
renewalDate | string | ISO date when license will be renewed. (Autogenerated). | |
renewalDaysFromNow | integer | Number of days till the next renewal. (Autogenerated). | |
isOverdue | boolean | Flag the license as overdue. (Autogenerated). | |
autoRenews | boolean | If set to true Planhat can automatically renew the subscription for you once the notice period is passed. Necessary for noticePeriod and noticeUnit to be autogenerated. Defaults to false. | |
noticePeriod | integer | Number of days/weeks/months before subscription ends that the license would have to be canceled not to automatically renew. Only makes sense if autoRenews is set to true. Defaults to 0. (Autogenerated). | |
noticeUnit | string | Unit for the noticePeriod, could be days/weeks/months. (Autogenerated). | |
renewalUnit | string | Unit for the noticePeriod, could be day/week/month. Defaults to month. | |
parent | string | Planhat ID of the ultimate parent license. | |
invoicesGenerated | boolean | Set to true for the invoices to not be autogenerated for the license upon creation. Default: false. | |
invoiceMuted | boolean | Set to true to disable the invoices creation when license renewal. Default: false. | |
invoiceCycleInterval | integer | Defines the custom cycle interval. (Autogenerated). | |
invoiceCycle | string | Cycle of the invoice. Could be one of: monthly, quarterly, yearly, semiAnnual, once or custom. (Autogenerated). | |
toDateIncluded | boolean | Set to true if the license has toDate. (Autogenerated). | |
length | number | Internal system field. (Autogenerated). | |
custom | object | A flexible object with custom data. |
Create license
To create a license the only real value that is required is the companyId but it doesn't make much sense to have a license just with a companyId, that is why we suggest specifying a value, _currency, and fromDate.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/licenses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"autoRenews": false,
"companyId": "61006bc89a3e0b702ed8ea49",
"fixedPeriod": true,
"fromDate": "2021-07-27T00:00:00.000Z",
"toDate": "2022-07-27T00:00:00.000Z",
"mrr": 83.33333333333333,
"product": "Large License",
"_currency": "USD",
"renewalPeriod": 12,
"renewalStatus": "ongoing"
}'
Example Response
'{
"renewalStatus": "ongoing",
"issues": [],
"autoRenews": false,
"noticePeriod": null,
"renewalUnit": "month",
"noticeUnit": null,
"invoicesGenerated": false,
"_id": "61006fbf1df7fa77a20d9d0a",
"companyId": "61006bc89a3e0b702ed8ea49",
"fixedPeriod": true,
"fromDate": "2021-07-27T00:00:00.000Z",
"toDate": "2022-07-27T00:00:00.000Z",
"invoiceCycleInterval": 0,
"mrr": 83.33333333333333,
"product": "Large License",
"_currency": "USD",
"renewalPeriod": 12,
"companyName": "Tenet",
"toDateIncluded": false,
"length": 12,
"value": 1000,
"renewalDate": "2022-07-27T00:00:00.000Z",
"renewalDaysFromNow": 364,
"isOverdue": false,
"__v": 0
}'Create license
To create a license the only real value that is required is the companyId but it doesn't make much sense to have a license just with a companyId, that is why we suggest specifying a value, _currency, and fromDate.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/licenses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"autoRenews": false,
"companyId": "61006bc89a3e0b702ed8ea49",
"fixedPeriod": true,
"fromDate": "2021-07-27T00:00:00.000Z",
"toDate": "2022-07-27T00:00:00.000Z",
"mrr": 83.33333333333333,
"product": "Large License",
"_currency": "USD",
"renewalPeriod": 12,
"renewalStatus": "ongoing"
}'
Example Response
'{
"renewalStatus": "ongoing",
"issues": [],
"autoRenews": false,
"noticePeriod": null,
"renewalUnit": "month",
"noticeUnit": null,
"invoicesGenerated": false,
"_id": "61006fbf1df7fa77a20d9d0a",
"companyId": "61006bc89a3e0b702ed8ea49",
"fixedPeriod": true,
"fromDate": "2021-07-27T00:00:00.000Z",
"toDate": "2022-07-27T00:00:00.000Z",
"invoiceCycleInterval": 0,
"mrr": 83.33333333333333,
"product": "Large License",
"_currency": "USD",
"renewalPeriod": 12,
"companyName": "Tenet",
"toDateIncluded": false,
"length": 12,
"value": 1000,
"renewalDate": "2022-07-27T00:00:00.000Z",
"renewalDaysFromNow": 364,
"isOverdue": false,
"__v": 0
}'Create license
To create a license the only real value that is required is the companyId but it doesn't make much sense to have a license just with a companyId, that is why we suggest specifying a value, _currency, and fromDate.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/licenses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"autoRenews": false,
"companyId": "61006bc89a3e0b702ed8ea49",
"fixedPeriod": true,
"fromDate": "2021-07-27T00:00:00.000Z",
"toDate": "2022-07-27T00:00:00.000Z",
"mrr": 83.33333333333333,
"product": "Large License",
"_currency": "USD",
"renewalPeriod": 12,
"renewalStatus": "ongoing"
}'
Example Response
'{
"renewalStatus": "ongoing",
"issues": [],
"autoRenews": false,
"noticePeriod": null,
"renewalUnit": "month",
"noticeUnit": null,
"invoicesGenerated": false,
"_id": "61006fbf1df7fa77a20d9d0a",
"companyId": "61006bc89a3e0b702ed8ea49",
"fixedPeriod": true,
"fromDate": "2021-07-27T00:00:00.000Z",
"toDate": "2022-07-27T00:00:00.000Z",
"invoiceCycleInterval": 0,
"mrr": 83.33333333333333,
"product": "Large License",
"_currency": "USD",
"renewalPeriod": 12,
"companyName": "Tenet",
"toDateIncluded": false,
"length": 12,
"value": 1000,
"renewalDate": "2022-07-27T00:00:00.000Z",
"renewalDaysFromNow": 364,
"isOverdue": false,
"__v": 0
}'Update license
To update a license it's required to pass the license _id in the request URL as a parameter.
Alternately it’s possible to update using the license externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/licenses/61006fbf1df7fa77a20d9d0a' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"mrr": 100000
}'
Example Response
'{
"_id": "61006fbf1df7fa77a20d9d0a",
"renewalStatus": "ongoing",
"issues": [],
"autoRenews": false,
"noticePeriod": null,
"renewalUnit": "month",
"noticeUnit": null,
"invoicesGenerated": false,
"companyId": "61006bc89a3e0b702ed8ea49",
"fixedPeriod": true,
"fromDate": "2021-07-27T00:00:00.000Z",
"toDate": "2022-07-27T00:00:00.000Z",
"invoiceCycleInterval": 0,
"mrr": 100000,
"product": "Large License",
"_currency": "USD",
"renewalPeriod": 12,
"companyName": "Tenet",
"toDateIncluded": false,
"length": 12,
"value": 1200000,
"renewalDate": "2022-07-27T00:00:00.000Z",
"renewalDaysFromNow": 364,
"isOverdue": false,
"__v": 0
}'Update license
To update a license it's required to pass the license _id in the request URL as a parameter.
Alternately it’s possible to update using the license externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/licenses/61006fbf1df7fa77a20d9d0a' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"mrr": 100000
}'
Example Response
'{
"_id": "61006fbf1df7fa77a20d9d0a",
"renewalStatus": "ongoing",
"issues": [],
"autoRenews": false,
"noticePeriod": null,
"renewalUnit": "month",
"noticeUnit": null,
"invoicesGenerated": false,
"companyId": "61006bc89a3e0b702ed8ea49",
"fixedPeriod": true,
"fromDate": "2021-07-27T00:00:00.000Z",
"toDate": "2022-07-27T00:00:00.000Z",
"invoiceCycleInterval": 0,
"mrr": 100000,
"product": "Large License",
"_currency": "USD",
"renewalPeriod": 12,
"companyName": "Tenet",
"toDateIncluded": false,
"length": 12,
"value": 1200000,
"renewalDate": "2022-07-27T00:00:00.000Z",
"renewalDaysFromNow": 364,
"isOverdue": false,
"__v": 0
}'Update license
To update a license it's required to pass the license _id in the request URL as a parameter.
Alternately it’s possible to update using the license externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/licenses/61006fbf1df7fa77a20d9d0a' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"mrr": 100000
}'
Example Response
'{
"_id": "61006fbf1df7fa77a20d9d0a",
"renewalStatus": "ongoing",
"issues": [],
"autoRenews": false,
"noticePeriod": null,
"renewalUnit": "month",
"noticeUnit": null,
"invoicesGenerated": false,
"companyId": "61006bc89a3e0b702ed8ea49",
"fixedPeriod": true,
"fromDate": "2021-07-27T00:00:00.000Z",
"toDate": "2022-07-27T00:00:00.000Z",
"invoiceCycleInterval": 0,
"mrr": 100000,
"product": "Large License",
"_currency": "USD",
"renewalPeriod": 12,
"companyName": "Tenet",
"toDateIncluded": false,
"length": 12,
"value": 1200000,
"renewalDate": "2022-07-27T00:00:00.000Z",
"renewalDaysFromNow": 364,
"isOverdue": false,
"__v": 0
}'Get licenses by ID
To get a specific license it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a license using its externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/licenses/56bccdf554d64d837d01beb2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "56bccdf554d64d837d01beb2",
"renewalStatus": "renewed",
"issues": null,
"autoRenews": false,
"noticePeriod": null,
"renewalUnit": "month",
"noticeUnit": null,
"invoicesGenerated": false,
"isOverdue": false,
"renewalDaysFromNow": -1313,
"renewalDate": "2017-12-22T00:00:00.000Z",
"mrr": 1958.3333333333333,
"length": 24,
"fixedPeriod": true,
"product": "",
"value": 47000,
"_currency": "USD",
"fromDate": "2015-12-22T00:00:00.000Z",
"toDate": "2017-12-22T00:00:00.000Z",
"salesDate": "2015-12-22T18:07:49.000Z",
"renewalPeriod": 24,
"toDateIncluded": false,
"invoiceCycleInterval": 0,
"sourceId": "0060O00000xdyr4QAA",
"companyId": "56bccdf554d64d837d01beaf",
"companyName": "Siemens",
"custom": {
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Days until renewal": -1,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
}
}'Get licenses by ID
To get a specific license it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a license using its externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/licenses/56bccdf554d64d837d01beb2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "56bccdf554d64d837d01beb2",
"renewalStatus": "renewed",
"issues": null,
"autoRenews": false,
"noticePeriod": null,
"renewalUnit": "month",
"noticeUnit": null,
"invoicesGenerated": false,
"isOverdue": false,
"renewalDaysFromNow": -1313,
"renewalDate": "2017-12-22T00:00:00.000Z",
"mrr": 1958.3333333333333,
"length": 24,
"fixedPeriod": true,
"product": "",
"value": 47000,
"_currency": "USD",
"fromDate": "2015-12-22T00:00:00.000Z",
"toDate": "2017-12-22T00:00:00.000Z",
"salesDate": "2015-12-22T18:07:49.000Z",
"renewalPeriod": 24,
"toDateIncluded": false,
"invoiceCycleInterval": 0,
"sourceId": "0060O00000xdyr4QAA",
"companyId": "56bccdf554d64d837d01beaf",
"companyName": "Siemens",
"custom": {
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Days until renewal": -1,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
}
}'Get licenses by ID
To get a specific license it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a license using its externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/licenses/56bccdf554d64d837d01beb2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "56bccdf554d64d837d01beb2",
"renewalStatus": "renewed",
"issues": null,
"autoRenews": false,
"noticePeriod": null,
"renewalUnit": "month",
"noticeUnit": null,
"invoicesGenerated": false,
"isOverdue": false,
"renewalDaysFromNow": -1313,
"renewalDate": "2017-12-22T00:00:00.000Z",
"mrr": 1958.3333333333333,
"length": 24,
"fixedPeriod": true,
"product": "",
"value": 47000,
"_currency": "USD",
"fromDate": "2015-12-22T00:00:00.000Z",
"toDate": "2017-12-22T00:00:00.000Z",
"salesDate": "2015-12-22T18:07:49.000Z",
"renewalPeriod": 24,
"toDateIncluded": false,
"invoiceCycleInterval": 0,
"sourceId": "0060O00000xdyr4QAA",
"companyId": "56bccdf554d64d837d01beaf",
"companyName": "Siemens",
"custom": {
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Days until renewal": -1,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
}
}'Get licenses List
When fetching multiple licenses there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default as 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/licenses?limit=2&offset=0&sort=-value&select=_id,product,value,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "601188a152181c5640bf429f",
"companyId": "6011889f52181c5640bf41bb",
"value": 292500
},
{
"_id": "598b7911c488358437484797",
"value": 280950,
"product": "",
"companyId": "598b78ef49c568a81b052f49"
}
]
Get licenses List
When fetching multiple licenses there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default as 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/licenses?limit=2&offset=0&sort=-value&select=_id,product,value,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "601188a152181c5640bf429f",
"companyId": "6011889f52181c5640bf41bb",
"value": 292500
},
{
"_id": "598b7911c488358437484797",
"value": 280950,
"product": "",
"companyId": "598b78ef49c568a81b052f49"
}
]
Get licenses List
When fetching multiple licenses there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default as 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/licenses?limit=2&offset=0&sort=-value&select=_id,product,value,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "601188a152181c5640bf429f",
"companyId": "6011889f52181c5640bf41bb",
"value": 292500
},
{
"_id": "598b7911c488358437484797",
"value": 280950,
"product": "",
"companyId": "598b78ef49c568a81b052f49"
}
]
Delete licenses
To delete a license it's required to pass the _id in the request URL as a parameter.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/licenses/61006fbf1df7fa77a20d9d0a' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Delete licenses
To delete a license it's required to pass the _id in the request URL as a parameter.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/licenses/61006fbf1df7fa77a20d9d0a' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Delete licenses
To delete a license it's required to pass the _id in the request URL as a parameter.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/licenses/61006fbf1df7fa77a20d9d0a' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Bulk Upsert licenses
To create a license it's required to define a companyId, _currency, and value.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To update a license it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId, externalId.
Since this is a bulk upsert operation it's possible to create and/or update multiple licenses with the same payload.
For more details please refer to the bulk upsert section.
Note: There is an upper limit of 5,000 items per request.
Example Request
curl --location -g --request PUT 'https://api.planhat.com/licenses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"_id": "6100772b919fd37905810fc6",
"mrr": 200000
},
{
"autoRenews": false,
"companyId": "61006bc89a3e0b702ed8ea49",
"fixedPeriod": true,
"fromDate": "2021-07-28T00:00:00.000Z",
"toDate": "2022-07-28T00:00:00.000Z",
"invoiceCycleInterval": 0,
"mrr": 100,
"product": "Large License",
"_currency": "USD",
"renewalPeriod": 12,
"renewalStatus": "ongoing"
}
]'
Example Response
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "61007752919fd37905810ff5"
}
],
"updated": 1,
"updatedErrors": [],
"updatesKeys": [
{
"_id": "6100772b919fd37905810fc6"
}
],
"nonupdates": 0,
"modified": [
"6100772b919fd37905810fc6"
],
"upsertedIds": [
"61007752919fd37905810ff5"
],
"permissionErrors": []
}'Bulk Upsert licenses
To create a license it's required to define a companyId, _currency, and value.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To update a license it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId, externalId.
Since this is a bulk upsert operation it's possible to create and/or update multiple licenses with the same payload.
For more details please refer to the bulk upsert section.
Note: There is an upper limit of 5,000 items per request.
Example Request
curl --location -g --request PUT 'https://api.planhat.com/licenses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"_id": "6100772b919fd37905810fc6",
"mrr": 200000
},
{
"autoRenews": false,
"companyId": "61006bc89a3e0b702ed8ea49",
"fixedPeriod": true,
"fromDate": "2021-07-28T00:00:00.000Z",
"toDate": "2022-07-28T00:00:00.000Z",
"invoiceCycleInterval": 0,
"mrr": 100,
"product": "Large License",
"_currency": "USD",
"renewalPeriod": 12,
"renewalStatus": "ongoing"
}
]'
Example Response
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "61007752919fd37905810ff5"
}
],
"updated": 1,
"updatedErrors": [],
"updatesKeys": [
{
"_id": "6100772b919fd37905810fc6"
}
],
"nonupdates": 0,
"modified": [
"6100772b919fd37905810fc6"
],
"upsertedIds": [
"61007752919fd37905810ff5"
],
"permissionErrors": []
}'Bulk Upsert licenses
To create a license it's required to define a companyId, _currency, and value.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To update a license it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId, externalId.
Since this is a bulk upsert operation it's possible to create and/or update multiple licenses with the same payload.
For more details please refer to the bulk upsert section.
Note: There is an upper limit of 5,000 items per request.
Example Request
curl --location -g --request PUT 'https://api.planhat.com/licenses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"_id": "6100772b919fd37905810fc6",
"mrr": 200000
},
{
"autoRenews": false,
"companyId": "61006bc89a3e0b702ed8ea49",
"fixedPeriod": true,
"fromDate": "2021-07-28T00:00:00.000Z",
"toDate": "2022-07-28T00:00:00.000Z",
"invoiceCycleInterval": 0,
"mrr": 100,
"product": "Large License",
"_currency": "USD",
"renewalPeriod": 12,
"renewalStatus": "ongoing"
}
]'
Example Response
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "61007752919fd37905810ff5"
}
],
"updated": 1,
"updatedErrors": [],
"updatesKeys": [
{
"_id": "6100772b919fd37905810fc6"
}
],
"nonupdates": 0,
"modified": [
"6100772b919fd37905810fc6"
],
"upsertedIds": [
"61007752919fd37905810ff5"
],
"permissionErrors": []
}'