Developers
Developers
Churn
The Churn model in Planhat is used to log and track reasons why customers churn, helping you understand and address churn to improve customer retention. You can record primary, secondary, or tertiary churn reasons using custom fields, and mark churn at the company or license level. Note: This is a placeholder description adapted from the Planhat Help Center, as no explicit Churn API section was found in the provided snippets. Please provide the correct Churn snippet for accurate API details.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
isChurn | Yes | boolean | Indicates if the record represents a churn event. |
churnReason | string | Reason for the churn (e.g., "Product Issues", "Lack of Features"). | |
externalId | string | External id in your system. | |
createDate | string | ISO date of creation. (Autogenerated). | |
custom | object | Custom object with your custom properties (e.g., secondary or tertiary churn reasons). |
The Churn model in Planhat is used to log and track reasons why customers churn, helping you understand and address churn to improve customer retention. You can record primary, secondary, or tertiary churn reasons using custom fields, and mark churn at the company or license level. Note: This is a placeholder description adapted from the Planhat Help Center, as no explicit Churn API section was found in the provided snippets. Please provide the correct Churn snippet for accurate API details.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
isChurn | Yes | boolean | Indicates if the record represents a churn event. |
churnReason | string | Reason for the churn (e.g., "Product Issues", "Lack of Features"). | |
externalId | string | External id in your system. | |
createDate | string | ISO date of creation. (Autogenerated). | |
custom | object | Custom object with your custom properties (e.g., secondary or tertiary churn reasons). |
The Churn model in Planhat is used to log and track reasons why customers churn, helping you understand and address churn to improve customer retention. You can record primary, secondary, or tertiary churn reasons using custom fields, and mark churn at the company or license level. Note: This is a placeholder description adapted from the Planhat Help Center, as no explicit Churn API section was found in the provided snippets. Please provide the correct Churn snippet for accurate API details.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
isChurn | Yes | boolean | Indicates if the record represents a churn event. |
churnReason | string | Reason for the churn (e.g., "Product Issues", "Lack of Features"). | |
externalId | string | External id in your system. | |
createDate | string | ISO date of creation. (Autogenerated). | |
custom | object | Custom object with your custom properties (e.g., secondary or tertiary churn reasons). |
Create churn
To create a churn record it's required to define a companyId and isChurn. Note: This is a placeholder, as no Churn API endpoints were found in the provided snippets. Please provide the correct snippet for accurate details.
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/churn' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"churnDate": "2021-07-28",
"reasons": [
"Change in leadership",
"Budget cuts"
],
"value": 2000,
"currency": "USD",
"comment": "This account could return in the future",
"companyId": "61006bc89a3e0b702ed8ea49"
}'
Example Response
'{
"snoozed": false,
"products": [],
"reasons": [
"Change in leadership",
"Budget cuts"
],
"_id": "6101d1f072c0e0884d5e8f57",
"churnDate": "2021-07-28T00:00:00.000Z",
"value": 2000,
"currency": "USD",
"comment": "This account could return in the future",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'Create churn
To create a churn record it's required to define a companyId and isChurn. Note: This is a placeholder, as no Churn API endpoints were found in the provided snippets. Please provide the correct snippet for accurate details.
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/churn' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"churnDate": "2021-07-28",
"reasons": [
"Change in leadership",
"Budget cuts"
],
"value": 2000,
"currency": "USD",
"comment": "This account could return in the future",
"companyId": "61006bc89a3e0b702ed8ea49"
}'
Example Response
'{
"snoozed": false,
"products": [],
"reasons": [
"Change in leadership",
"Budget cuts"
],
"_id": "6101d1f072c0e0884d5e8f57",
"churnDate": "2021-07-28T00:00:00.000Z",
"value": 2000,
"currency": "USD",
"comment": "This account could return in the future",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'Create churn
To create a churn record it's required to define a companyId and isChurn. Note: This is a placeholder, as no Churn API endpoints were found in the provided snippets. Please provide the correct snippet for accurate details.
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/churn' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"churnDate": "2021-07-28",
"reasons": [
"Change in leadership",
"Budget cuts"
],
"value": 2000,
"currency": "USD",
"comment": "This account could return in the future",
"companyId": "61006bc89a3e0b702ed8ea49"
}'
Example Response
'{
"snoozed": false,
"products": [],
"reasons": [
"Change in leadership",
"Budget cuts"
],
"_id": "6101d1f072c0e0884d5e8f57",
"churnDate": "2021-07-28T00:00:00.000Z",
"value": 2000,
"currency": "USD",
"comment": "This account could return in the future",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'Update churn
To update a churn record it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the externalId adding a prefix and passing it as an identifier.
Example:
Example Request
curl --location -g --request PUT 'https://api.planhat.com/churn/6101d1f072c0e0884d5e8f57' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"value": 25000
}'
Example Response
'{
"_id": "6101d1f072c0e0884d5e8f57",
"snoozed": false,
"products": [],
"reasons": [
"Change in leadership",
"Budget cuts"
],
"churnDate": "2021-07-28T00:00:00.000Z",
"value": 25000,
"currency": "USD",
"comment": "This account could return in the future",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'Update churn
To update a churn record it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the externalId adding a prefix and passing it as an identifier.
Example:
Example Request
curl --location -g --request PUT 'https://api.planhat.com/churn/6101d1f072c0e0884d5e8f57' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"value": 25000
}'
Example Response
'{
"_id": "6101d1f072c0e0884d5e8f57",
"snoozed": false,
"products": [],
"reasons": [
"Change in leadership",
"Budget cuts"
],
"churnDate": "2021-07-28T00:00:00.000Z",
"value": 25000,
"currency": "USD",
"comment": "This account could return in the future",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'Update churn
To update a churn record it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the externalId adding a prefix and passing it as an identifier.
Example:
Example Request
curl --location -g --request PUT 'https://api.planhat.com/churn/6101d1f072c0e0884d5e8f57' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"value": 25000
}'
Example Response
'{
"_id": "6101d1f072c0e0884d5e8f57",
"snoozed": false,
"products": [],
"reasons": [
"Change in leadership",
"Budget cuts"
],
"churnDate": "2021-07-28T00:00:00.000Z",
"value": 25000,
"currency": "USD",
"comment": "This account could return in the future",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'Get churn by ID
To get a specific churn record it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a churn record using its externalId adding a prefix and passing it as an identifier.
Example:
Example Request
curl --location -g --request GET 'https://api.planhat.com/churn/58cc4b769649cb337f9d59a9' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "58cc4b769649cb337f9d59a9",
"licenseId": "56bccdf554d64d837d01be5b",
"reasons": [
"Missing features"
],
"comment": "",
"replacement": "",
"companyId": "56bccdf554d64d837d01be59",
"__v": 0,
"companyName": "t2",
"churnDate": "2017-07-29T00:07:49.000Z",
"products": [
"License Fee"
],
"currency": "USD",
"value": 3979.1666666666665,
"custom": null
}'Get churn by ID
To get a specific churn record it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a churn record using its externalId adding a prefix and passing it as an identifier.
Example:
Example Request
curl --location -g --request GET 'https://api.planhat.com/churn/58cc4b769649cb337f9d59a9' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "58cc4b769649cb337f9d59a9",
"licenseId": "56bccdf554d64d837d01be5b",
"reasons": [
"Missing features"
],
"comment": "",
"replacement": "",
"companyId": "56bccdf554d64d837d01be59",
"__v": 0,
"companyName": "t2",
"churnDate": "2017-07-29T00:07:49.000Z",
"products": [
"License Fee"
],
"currency": "USD",
"value": 3979.1666666666665,
"custom": null
}'Get churn by ID
To get a specific churn record it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a churn record using its externalId adding a prefix and passing it as an identifier.
Example:
Example Request
curl --location -g --request GET 'https://api.planhat.com/churn/58cc4b769649cb337f9d59a9' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "58cc4b769649cb337f9d59a9",
"licenseId": "56bccdf554d64d837d01be5b",
"reasons": [
"Missing features"
],
"comment": "",
"replacement": "",
"companyId": "56bccdf554d64d837d01be59",
"__v": 0,
"companyName": "t2",
"churnDate": "2017-07-29T00:07:49.000Z",
"products": [
"License Fee"
],
"currency": "USD",
"value": 3979.1666666666665,
"custom": null
}'Get churn List
When fetching multiple churn records 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/churn' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "583b8d15f075d7b52cd392e2",
"licenseId": "56bccdf654d64d837d01d812",
"reasons": [
"Customer got acquired"
],
"comment": "notes..",
"replacement": "",
"companyId": "56bccdf554d64d837d01be6f",
"__v": 0,
"companyName": "CBS",
"churnDate": "2020-10-10T00:00:00.000Z",
"products": [
"License Fee"
],
"currency": "USD",
"value": 5000,
"custom": null,
"lastUpdated": "2020-10-08T15:09:29.982Z"
},
{
"_id": "58cc4b769649cb337f9d59a9",
"licenseId": "56bccdf554d64d837d01be5b",
"reasons": [
"Missing features"
],
"comment": "",
"replacement": "",
"companyId": "56bccdf554d64d837d01be59",
"__v": 0,
"companyName": "t2",
"churnDate": "2017-07-29T00:07:49.000Z",
"products": [
"License Fee"
],
"currency": "USD",
"value": 3979.1666666666665,
"custom": null
}
]'Get churn List
When fetching multiple churn records 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/churn' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "583b8d15f075d7b52cd392e2",
"licenseId": "56bccdf654d64d837d01d812",
"reasons": [
"Customer got acquired"
],
"comment": "notes..",
"replacement": "",
"companyId": "56bccdf554d64d837d01be6f",
"__v": 0,
"companyName": "CBS",
"churnDate": "2020-10-10T00:00:00.000Z",
"products": [
"License Fee"
],
"currency": "USD",
"value": 5000,
"custom": null,
"lastUpdated": "2020-10-08T15:09:29.982Z"
},
{
"_id": "58cc4b769649cb337f9d59a9",
"licenseId": "56bccdf554d64d837d01be5b",
"reasons": [
"Missing features"
],
"comment": "",
"replacement": "",
"companyId": "56bccdf554d64d837d01be59",
"__v": 0,
"companyName": "t2",
"churnDate": "2017-07-29T00:07:49.000Z",
"products": [
"License Fee"
],
"currency": "USD",
"value": 3979.1666666666665,
"custom": null
}
]'Get churn List
When fetching multiple churn records 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/churn' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "583b8d15f075d7b52cd392e2",
"licenseId": "56bccdf654d64d837d01d812",
"reasons": [
"Customer got acquired"
],
"comment": "notes..",
"replacement": "",
"companyId": "56bccdf554d64d837d01be6f",
"__v": 0,
"companyName": "CBS",
"churnDate": "2020-10-10T00:00:00.000Z",
"products": [
"License Fee"
],
"currency": "USD",
"value": 5000,
"custom": null,
"lastUpdated": "2020-10-08T15:09:29.982Z"
},
{
"_id": "58cc4b769649cb337f9d59a9",
"licenseId": "56bccdf554d64d837d01be5b",
"reasons": [
"Missing features"
],
"comment": "",
"replacement": "",
"companyId": "56bccdf554d64d837d01be59",
"__v": 0,
"companyName": "t2",
"churnDate": "2017-07-29T00:07:49.000Z",
"products": [
"License Fee"
],
"currency": "USD",
"value": 3979.1666666666665,
"custom": null
}
]'Delete churn
To delete a churn record 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/churn/6101d1f072c0e0884d5e8f57' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Delete churn
To delete a churn record 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/churn/6101d1f072c0e0884d5e8f57' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Delete churn
To delete a churn record 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/churn/6101d1f072c0e0884d5e8f57' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Bulk Upsert churn
To create a churn record it's required to define a companyId and isChurn.
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 churn record it is required to specify in the payload one of the following keyables, listed in order of priority: _id, externalId.
Since this is a bulk upsert operation it's possible to create and/or update multiple churn records 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/churn' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"churnDate": "2021-07-29",
"reasons": [
"Change in leadership",
"Budget cuts"
],
"value": 2500,
"currency": "USD",
"comment": "This account could return in the future",
"companyId": "61006bc89a3e0b702ed8ea49"
},
{
"_id": "60e5d4dabe45b22e8e97940c",
"comment": "New communication with the CEO, the could return next year"
}
]'
Example Response
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101d5dc72c0e0884d5e9002"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101d5dc72c0e0884d5e9002"
],
"permissionErrors": []
}'Bulk Upsert churn
To create a churn record it's required to define a companyId and isChurn.
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 churn record it is required to specify in the payload one of the following keyables, listed in order of priority: _id, externalId.
Since this is a bulk upsert operation it's possible to create and/or update multiple churn records 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/churn' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"churnDate": "2021-07-29",
"reasons": [
"Change in leadership",
"Budget cuts"
],
"value": 2500,
"currency": "USD",
"comment": "This account could return in the future",
"companyId": "61006bc89a3e0b702ed8ea49"
},
{
"_id": "60e5d4dabe45b22e8e97940c",
"comment": "New communication with the CEO, the could return next year"
}
]'
Example Response
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101d5dc72c0e0884d5e9002"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101d5dc72c0e0884d5e9002"
],
"permissionErrors": []
}'Bulk Upsert churn
To create a churn record it's required to define a companyId and isChurn.
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 churn record it is required to specify in the payload one of the following keyables, listed in order of priority: _id, externalId.
Since this is a bulk upsert operation it's possible to create and/or update multiple churn records 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/churn' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"churnDate": "2021-07-29",
"reasons": [
"Change in leadership",
"Budget cuts"
],
"value": 2500,
"currency": "USD",
"comment": "This account could return in the future",
"companyId": "61006bc89a3e0b702ed8ea49"
},
{
"_id": "60e5d4dabe45b22e8e97940c",
"comment": "New communication with the CEO, the could return next year"
}
]'
Example Response
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101d5dc72c0e0884d5e9002"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101d5dc72c0e0884d5e9002"
],
"permissionErrors": []
}'