Planhat | Product

https://api.planhat.com/products

A product represents a subscription plan or one-off fee that can be sold to customers. Products act as templates for line items - when a product is assigned to a line item, its default values (type, pricing, period, renewal terms) are inherited. This ensures consistency across deals and makes revenue reporting more structured.

Property	Required	Type	Description
`_id`		objectId	Planhat identifier.
`name`	Yes	string	Product name.
`externalId`		string	The product id in your own system.
`sourceId`		string	The product id from an integration (Salesforce, HubSpot, etc).
`type`		string	Product type. Either subscription or fee. Defaults to subscription.
`mrr`		number	Default Monthly Recurring Revenue for this product.
`arr`		number	Default Annual Recurring Revenue. Calculated from mrr. (Autogenerated).
`value`		number	Default value. Used as the primary revenue field when type is fee.
`currency`		string	Default currency for this product.
`fixedPeriod`		boolean	Whether line items for this product have a fixed end date by default.
`autoRenews`		boolean	Whether line items for this product auto-renew by default.
`length`		number	Default subscription length in months.
`renewalMrr`		number	Default expected MRR at renewal.
`renewalArr`		number	Default expected ARR at renewal. Calculated from renewalMrr. (Autogenerated).
`renewalPeriod`		number	Default renewal period length in months.
`noticePeriod`		number	Default notice period length.
`noticeUnit`		string	Unit for the notice period. One of day, week, month.
`packages`		array	Array of package names this product belongs to.
`color`		string	Display color for the product in the UI.
`custom`		object	A flexible object with custom data.
`createdAt`		date time	ISO date when the product was created. (Autogenerated).
`updatedAt`		date time	ISO date when the product was last updated. (Autogenerated).

https://api.planhat.com/products

A product represents a subscription plan or one-off fee that can be sold to customers. Products act as templates for line items - when a product is assigned to a line item, its default values (type, pricing, period, renewal terms) are inherited. This ensures consistency across deals and makes revenue reporting more structured.

Property	Required	Type	Description
`_id`		objectId	Planhat identifier.
`name`	Yes	string	Product name.
`externalId`		string	The product id in your own system.
`sourceId`		string	The product id from an integration (Salesforce, HubSpot, etc).
`type`		string	Product type. Either subscription or fee. Defaults to subscription.
`mrr`		number	Default Monthly Recurring Revenue for this product.
`arr`		number	Default Annual Recurring Revenue. Calculated from mrr. (Autogenerated).
`value`		number	Default value. Used as the primary revenue field when type is fee.
`currency`		string	Default currency for this product.
`fixedPeriod`		boolean	Whether line items for this product have a fixed end date by default.
`autoRenews`		boolean	Whether line items for this product auto-renew by default.
`length`		number	Default subscription length in months.
`renewalMrr`		number	Default expected MRR at renewal.
`renewalArr`		number	Default expected ARR at renewal. Calculated from renewalMrr. (Autogenerated).
`renewalPeriod`		number	Default renewal period length in months.
`noticePeriod`		number	Default notice period length.
`noticeUnit`		string	Unit for the notice period. One of day, week, month.
`packages`		array	Array of package names this product belongs to.
`color`		string	Display color for the product in the UI.
`custom`		object	A flexible object with custom data.
`createdAt`		date time	ISO date when the product was created. (Autogenerated).
`updatedAt`		date time	ISO date when the product was last updated. (Autogenerated).

https://api.planhat.com/products

A product represents a subscription plan or one-off fee that can be sold to customers. Products act as templates for line items - when a product is assigned to a line item, its default values (type, pricing, period, renewal terms) are inherited. This ensures consistency across deals and makes revenue reporting more structured.

Property	Required	Type	Description
`_id`		objectId	Planhat identifier.
`name`	Yes	string	Product name.
`externalId`		string	The product id in your own system.
`sourceId`		string	The product id from an integration (Salesforce, HubSpot, etc).
`type`		string	Product type. Either subscription or fee. Defaults to subscription.
`mrr`		number	Default Monthly Recurring Revenue for this product.
`arr`		number	Default Annual Recurring Revenue. Calculated from mrr. (Autogenerated).
`value`		number	Default value. Used as the primary revenue field when type is fee.
`currency`		string	Default currency for this product.
`fixedPeriod`		boolean	Whether line items for this product have a fixed end date by default.
`autoRenews`		boolean	Whether line items for this product auto-renew by default.
`length`		number	Default subscription length in months.
`renewalMrr`		number	Default expected MRR at renewal.
`renewalArr`		number	Default expected ARR at renewal. Calculated from renewalMrr. (Autogenerated).
`renewalPeriod`		number	Default renewal period length in months.
`noticePeriod`		number	Default notice period length.
`noticeUnit`		string	Unit for the notice period. One of day, week, month.
`packages`		array	Array of package names this product belongs to.
`color`		string	Display color for the product in the UI.
`custom`		object	A flexible object with custom data.
`createdAt`		date time	ISO date when the product was created. (Autogenerated).
`updatedAt`		date time	ISO date when the product was last updated. (Autogenerated).

https://api.planhat.com/products

To create a product, name is required.

Example Request

curl --location -g --request POST 'https://api.planhat.com/products' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}' \
  --data-raw '{
    "name": "Platform — Growth",
    "type": "subscription",
    "mrr": 5000,
    "currency": "USD",
    "fixedPeriod": true,
    "autoRenews": true,
    "length": 12
  }

Example Response

200 ok

{
  "_id": "610097ab6d643a7c418af200",
  "name": "Platform — Growth",
  "type": "subscription",
  "mrr": 5000,
  "arr": 60000,
  "currency": "USD",
  "fixedPeriod": true,
  "autoRenews": true,
  "length": 12,
  "packages": [],
  "createdAt": "2026-05-15T10:00:00.000Z",
  "updatedAt": "2026-05-15T10:00:00.000Z"
}

https://api.planhat.com/products

To create a product, name is required.

Example Request

curl --location -g --request POST 'https://api.planhat.com/products' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}' \
  --data-raw '{
    "name": "Platform — Growth",
    "type": "subscription",
    "mrr": 5000,
    "currency": "USD",
    "fixedPeriod": true,
    "autoRenews": true,
    "length": 12
  }

Example Response

200 ok

{
  "_id": "610097ab6d643a7c418af200",
  "name": "Platform — Growth",
  "type": "subscription",
  "mrr": 5000,
  "arr": 60000,
  "currency": "USD",
  "fixedPeriod": true,
  "autoRenews": true,
  "length": 12,
  "packages": [],
  "createdAt": "2026-05-15T10:00:00.000Z",
  "updatedAt": "2026-05-15T10:00:00.000Z"
}

https://api.planhat.com/products

To create a product, name is required.

Example Request

curl --location -g --request POST 'https://api.planhat.com/products' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}' \
  --data-raw '{
    "name": "Platform — Growth",
    "type": "subscription",
    "mrr": 5000,
    "currency": "USD",
    "fixedPeriod": true,
    "autoRenews": true,
    "length": 12
  }

Example Response

200 ok

{
  "_id": "610097ab6d643a7c418af200",
  "name": "Platform — Growth",
  "type": "subscription",
  "mrr": 5000,
  "arr": 60000,
  "currency": "USD",
  "fixedPeriod": true,
  "autoRenews": true,
  "length": 12,
  "packages": [],
  "createdAt": "2026-05-15T10:00:00.000Z",
  "updatedAt": "2026-05-15T10:00:00.000Z"
}

https://api.planhat.com/products/:_id

To update a product, pass the _id in the request URL. Alternatively use a prefixed externalId or sourceId:

https://api.planhat.com/products/extid-{{externalId}}

or

https://api.planhat.com/products/srcid-{{sourceId}}

Example Request

curl --location -g --request PUT 'https://api.planhat.com/products/610097ab6d643a7c418af200' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}' \
  --data-raw '{
    "mrr": 6000,
    "packages": ["Enterprise"]
  }'

Example Response

200 ok

{
  "_id": "610097ab6d643a7c418af200",
  "name": "Platform — Growth",
  "type": "subscription",
  "mrr": 6000,
  "arr": 72000,
  "currency": "USD",
  "packages": ["Enterprise"],
  "updatedAt": "2026-05-15T10:05:00.000Z"
}

https://api.planhat.com/products/:_id

To update a product, pass the _id in the request URL. Alternatively use a prefixed externalId or sourceId:

https://api.planhat.com/products/extid-{{externalId}}

or

https://api.planhat.com/products/srcid-{{sourceId}}

Example Request

curl --location -g --request PUT 'https://api.planhat.com/products/610097ab6d643a7c418af200' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}' \
  --data-raw '{
    "mrr": 6000,
    "packages": ["Enterprise"]
  }'

Example Response

200 ok

{
  "_id": "610097ab6d643a7c418af200",
  "name": "Platform — Growth",
  "type": "subscription",
  "mrr": 6000,
  "arr": 72000,
  "currency": "USD",
  "packages": ["Enterprise"],
  "updatedAt": "2026-05-15T10:05:00.000Z"
}

https://api.planhat.com/products/:_id

To update a product, pass the _id in the request URL. Alternatively use a prefixed externalId or sourceId:

https://api.planhat.com/products/extid-{{externalId}}

or

https://api.planhat.com/products/srcid-{{sourceId}}

Example Request

curl --location -g --request PUT 'https://api.planhat.com/products/610097ab6d643a7c418af200' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}' \
  --data-raw '{
    "mrr": 6000,
    "packages": ["Enterprise"]
  }'

Example Response

200 ok

{
  "_id": "610097ab6d643a7c418af200",
  "name": "Platform — Growth",
  "type": "subscription",
  "mrr": 6000,
  "arr": 72000,
  "currency": "USD",
  "packages": ["Enterprise"],
  "updatedAt": "2026-05-15T10:05:00.000Z"
}

https://api.planhat.com/products/:_id

To get a specific product, pass the _id in the request URL. Alternatively use a prefixed externalId or sourceId:

https://api.planhat.com/products/extid-{{externalId}}

Or

https://api.planhat.com/products/srcid-{{sourceId}}

Example Request

curl --location -g --request GET 'https://api.planhat.com/products/610097ab6d643a7c418af200' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}'

https://api.planhat.com/products/:_id

To get a specific product, pass the _id in the request URL. Alternatively use a prefixed externalId or sourceId:

https://api.planhat.com/products/extid-{{externalId}}

Or

https://api.planhat.com/products/srcid-{{sourceId}}

Example Request

curl --location -g --request GET 'https://api.planhat.com/products/610097ab6d643a7c418af200' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}'

https://api.planhat.com/products/:_id

To get a specific product, pass the _id in the request URL. Alternatively use a prefixed externalId or sourceId:

https://api.planhat.com/products/extid-{{externalId}}

Or

https://api.planhat.com/products/srcid-{{sourceId}}

Example Request

curl --location -g --request GET 'https://api.planhat.com/products/610097ab6d643a7c418af200' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}'

https://api.planhat.com/products

The following query params are available:

limit — Limit the list length. Default 100, max 2000.
offset — Start the list at a specific integer index.
sort — Sort by a specific property. Prefix with - to reverse sort order.
select — Return specific properties only. Multiple properties separated by commas.

Example Request

curl --location -g --request GET 'https://api.planhat.com/products?limit=50' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}'

https://api.planhat.com/products

The following query params are available:

limit — Limit the list length. Default 100, max 2000.
offset — Start the list at a specific integer index.
sort — Sort by a specific property. Prefix with - to reverse sort order.
select — Return specific properties only. Multiple properties separated by commas.

Example Request

curl --location -g --request GET 'https://api.planhat.com/products?limit=50' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}'

https://api.planhat.com/products

The following query params are available:

limit — Limit the list length. Default 100, max 2000.
offset — Start the list at a specific integer index.
sort — Sort by a specific property. Prefix with - to reverse sort order.
select — Return specific properties only. Multiple properties separated by commas.

Example Request

curl --location -g --request GET 'https://api.planhat.com/products?limit=50' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}'

https://api.planhat.com/products/:_id

To delete a product, pass the _id in the request URL.

Example Request

curl --location -g --request DELETE 'https://api.planhat.com/products/610097ab6d643a7c418af200' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

{
  "n": 1,
  "ok": 1,
  "deletedCount": 1
}

https://api.planhat.com/products/:_id

To delete a product, pass the _id in the request URL.

Example Request

curl --location -g --request DELETE 'https://api.planhat.com/products/610097ab6d643a7c418af200' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

{
  "n": 1,
  "ok": 1,
  "deletedCount": 1
}

https://api.planhat.com/products/:_id

To delete a product, pass the _id in the request URL.

Example Request

curl --location -g --request DELETE 'https://api.planhat.com/products/610097ab6d643a7c418af200' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

{
  "n": 1,
  "ok": 1,
  "deletedCount": 1
}

https://api.planhat.com/products

To create a product, name is required. To update, specify one of the following keyables in the payload (in order of priority): _id, sourceId, externalId. There is an upper limit of 5,000 items per request.

Example Request

curl --location -g --request PUT 'https://api.planhat.com/products' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}' \
  --data-raw '[
    {
      "externalId": "prod-001",
      "name": "Platform — Starter",
      "type": "subscription",
      "mrr": 1000,
      "currency": "USD"
    },
    {
      "externalId": "prod-002",
      "name": "Onboarding Fee",
      "type": "fee",
      "value": 5000,
      "currency": "USD"
    }
  ]

Example Response

200 ok

{
  "created": 2,
  "createdErrors": [],
  "insertsKeys": [
    { "_id": "610097ab6d643a7c418af201", "externalId": "prod-001" },
    { "_id": "610097ab6d643a7c418af202", "externalId": "prod-002" }
  ],
  "updated": 0,
  "updatedErrors": [],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": ["610097ab6d643a7c418af201", "610097ab6d643a7c418af202"],
  "permissionErrors": []
}

https://api.planhat.com/products

To create a product, name is required. To update, specify one of the following keyables in the payload (in order of priority): _id, sourceId, externalId. There is an upper limit of 5,000 items per request.

Example Request

curl --location -g --request PUT 'https://api.planhat.com/products' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}' \
  --data-raw '[
    {
      "externalId": "prod-001",
      "name": "Platform — Starter",
      "type": "subscription",
      "mrr": 1000,
      "currency": "USD"
    },
    {
      "externalId": "prod-002",
      "name": "Onboarding Fee",
      "type": "fee",
      "value": 5000,
      "currency": "USD"
    }
  ]

Example Response

200 ok

{
  "created": 2,
  "createdErrors": [],
  "insertsKeys": [
    { "_id": "610097ab6d643a7c418af201", "externalId": "prod-001" },
    { "_id": "610097ab6d643a7c418af202", "externalId": "prod-002" }
  ],
  "updated": 0,
  "updatedErrors": [],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": ["610097ab6d643a7c418af201", "610097ab6d643a7c418af202"],
  "permissionErrors": []
}

https://api.planhat.com/products

To create a product, name is required. To update, specify one of the following keyables in the payload (in order of priority): _id, sourceId, externalId. There is an upper limit of 5,000 items per request.

Example Request

curl --location -g --request PUT 'https://api.planhat.com/products' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{apiToken}}' \
  --data-raw '[
    {
      "externalId": "prod-001",
      "name": "Platform — Starter",
      "type": "subscription",
      "mrr": 1000,
      "currency": "USD"
    },
    {
      "externalId": "prod-002",
      "name": "Onboarding Fee",
      "type": "fee",
      "value": 5000,
      "currency": "USD"
    }
  ]

Example Response

200 ok

{
  "created": 2,
  "createdErrors": [],
  "insertsKeys": [
    { "_id": "610097ab6d643a7c418af201", "externalId": "prod-001" },
    { "_id": "610097ab6d643a7c418af202", "externalId": "prod-002" }
  ],
  "updated": 0,
  "updatedErrors": [],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": ["610097ab6d643a7c418af201", "610097ab6d643a7c418af202"],
  "permissionErrors": []
}