Planhat Logo

Developers

Planhat Logo

Developers

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": []
 }'