Sale
The Sale (NRR) model represents non-recurring revenue, like an onboarding fee, or a one-off professional services project.
Property | Required | Type | Description |
---|---|---|---|
_id | objectId | Planhat identifier. | |
_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 sales with a currency code not yet available in your list of currencies. |
product | string | Name of the sales product. Not required but highly recommended. Even if you only have one product we suggest adding it as "Advanced Onboarding". | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The sale id in your own system. | |
sourceId | string | The sale id from an integration (Sales Force, Hubspot, etc). | |
salesDate | Yes | string | Date when sale happened in ISO format. |
value | Yes | number | The total sales value, must be positive. |
custom | object | A flexible object with custom data. |
The Sale (NRR) model represents non-recurring revenue, like an onboarding fee, or a one-off professional services project.
Property | Required | Type | Description |
---|---|---|---|
_id | objectId | Planhat identifier. | |
_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 sales with a currency code not yet available in your list of currencies. |
product | string | Name of the sales product. Not required but highly recommended. Even if you only have one product we suggest adding it as "Advanced Onboarding". | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The sale id in your own system. | |
sourceId | string | The sale id from an integration (Sales Force, Hubspot, etc). | |
salesDate | Yes | string | Date when sale happened in ISO format. |
value | Yes | number | The total sales value, must be positive. |
custom | object | A flexible object with custom data. |
The Sale (NRR) model represents non-recurring revenue, like an onboarding fee, or a one-off professional services project.
Property | Required | Type | Description |
---|---|---|---|
_id | objectId | Planhat identifier. | |
_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 sales with a currency code not yet available in your list of currencies. |
product | string | Name of the sales product. Not required but highly recommended. Even if you only have one product we suggest adding it as "Advanced Onboarding". | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The sale id in your own system. | |
sourceId | string | The sale id from an integration (Sales Force, Hubspot, etc). | |
salesDate | Yes | string | Date when sale happened in ISO format. |
value | Yes | number | The total sales value, must be positive. |
custom | object | A flexible object with custom data. |
Create sale
To create a sale the only real value that is required is the companyId but it doesn't make much sense to have a sale just with a companyId, that is why we suggest specifying a value and _currency.
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/sales' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"value": 10000,
"companyId": "61006bc89a3e0b702ed8ea49"
}'
Example Response
'{
"value": 10000,
"_id": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'
Create sale
To create a sale the only real value that is required is the companyId but it doesn't make much sense to have a sale just with a companyId, that is why we suggest specifying a value and _currency.
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/sales' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"value": 10000,
"companyId": "61006bc89a3e0b702ed8ea49"
}'
Example Response
'{
"value": 10000,
"_id": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'
Create sale
To create a sale the only real value that is required is the companyId but it doesn't make much sense to have a sale just with a companyId, that is why we suggest specifying a value and _currency.
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/sales' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"value": 10000,
"companyId": "61006bc89a3e0b702ed8ea49"
}'
Example Response
'{
"value": 10000,
"_id": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'
Update sale
To update a sale it's required to pass the sale _id in the request URL as a parameter.
Alternately it’s possible to update using the sale 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/sales/61016c80675c1b871faf2d4f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"mrr": 100000
}'
Example Response
'{
"_id": "61016c80675c1b871faf2d4f",
"value": 15000,
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'
Update sale
To update a sale it's required to pass the sale _id in the request URL as a parameter.
Alternately it’s possible to update using the sale 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/sales/61016c80675c1b871faf2d4f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"mrr": 100000
}'
Example Response
'{
"_id": "61016c80675c1b871faf2d4f",
"value": 15000,
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'
Update sale
To update a sale it's required to pass the sale _id in the request URL as a parameter.
Alternately it’s possible to update using the sale 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/sales/61016c80675c1b871faf2d4f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"mrr": 100000
}'
Example Response
'{
"_id": "61016c80675c1b871faf2d4f",
"value": 15000,
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'
Get sales by ID
To get a specific sale it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a sale 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/sales/61016c80675c1b871faf2d4f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"value": 10000,
"_id": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'
Get sales by ID
To get a specific sale it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a sale 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/sales/61016c80675c1b871faf2d4f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"value": 10000,
"_id": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'
Get sales by ID
To get a specific sale it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a sale 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/sales/61016c80675c1b871faf2d4f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"value": 10000,
"_id": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"__v": 0
}'
Get sales List
When fetching multiple sales 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/sales?limit=2&offset=0&sort=-value&select=_id,product,value,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "59e04a67b640bc9e7c71f4a0",
"product": "UpStart Meeting",
"value": 300000,
"companyId": "56ccc2d39b760ff232295795"
},
{
"_id": "59e04a44b640bc9e7c71f497",
"product": "UpStart Meeting",
"value": 300000,
"companyId": "56ccc2d39b760ff232295795"
}
]
Get sales List
When fetching multiple sales 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/sales?limit=2&offset=0&sort=-value&select=_id,product,value,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "59e04a67b640bc9e7c71f4a0",
"product": "UpStart Meeting",
"value": 300000,
"companyId": "56ccc2d39b760ff232295795"
},
{
"_id": "59e04a44b640bc9e7c71f497",
"product": "UpStart Meeting",
"value": 300000,
"companyId": "56ccc2d39b760ff232295795"
}
]
Get sales List
When fetching multiple sales 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/sales?limit=2&offset=0&sort=-value&select=_id,product,value,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "59e04a67b640bc9e7c71f4a0",
"product": "UpStart Meeting",
"value": 300000,
"companyId": "56ccc2d39b760ff232295795"
},
{
"_id": "59e04a44b640bc9e7c71f497",
"product": "UpStart Meeting",
"value": 300000,
"companyId": "56ccc2d39b760ff232295795"
}
]
Delete sales
To delete a sale 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/sales/61016c80675c1b871faf2d4f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'
Delete sales
To delete a sale 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/sales/61016c80675c1b871faf2d4f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'
Delete sales
To delete a sale 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/sales/61016c80675c1b871faf2d4f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'
Bulk Upsert sales
To create a sale 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 sale 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 sales 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/sales' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"value": 5000,
"companyId": "61006bc89a3e0b702ed8ea49"
},
{
"_id": "61016c80675c1b871faf2d4f",
"value": 200000
}
]'
Example Response
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101714572c0e0884d5e8160"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101714572c0e0884d5e8160"
],
"permissionErrors": []
}'
Bulk Upsert sales
To create a sale 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 sale 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 sales 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/sales' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"value": 5000,
"companyId": "61006bc89a3e0b702ed8ea49"
},
{
"_id": "61016c80675c1b871faf2d4f",
"value": 200000
}
]'
Example Response
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101714572c0e0884d5e8160"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101714572c0e0884d5e8160"
],
"permissionErrors": []
}'
Bulk Upsert sales
To create a sale 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 sale 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 sales 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/sales' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"product": "Advanced Onboarding",
"_currency": "USD",
"salesDate": "2021-07-28T00:00:00.000Z",
"value": 5000,
"companyId": "61006bc89a3e0b702ed8ea49"
},
{
"_id": "61016c80675c1b871faf2d4f",
"value": 200000
}
]'
Example Response
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101714572c0e0884d5e8160"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101714572c0e0884d5e8160"
],
"permissionErrors": []
}'