Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(data-warehouse): add churn, opportunities, line items and metrics to planhat (#126262)

Tom Owers59a784891ad1
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
index 8f27341a160f..aae1b8fa97ab 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
@@ -9540,11 +9540,11 @@ Diffed against: <https://docs.planhat.com/developers/api/planhat-models>
- [x] `ticket` — support tickets tied to companies, needed for health scoring (high)
- [x] `invoice` — billed revenue per company (high)
- [x] `sale` — closed revenue transactions (high)
-- [ ] `churn` — churn records, the headline customer-success metric (high)
-- [ ] `metrics` — time-series usage and health metrics per company; Planhat's central analytical object (high)
+- [x] `churn` — churn records, the headline customer-success metric (high)
+- [x] `metrics` — time-series usage and health metrics per company; Planhat's central analytical object (high)
- [ ] `product` — lookup resolving the product IDs carried on synced licenses and on line items (high)
-- [ ] `line-item` — line-level breakdown of licenses, invoices and sales (high)
-- [ ] `opportunity` — open pipeline against existing accounts (high)
+- [x] `line-item` — line-level breakdown of licenses, invoices and sales (high)
+- [x] `opportunity` — open pipeline against existing accounts (high)
- [ ] `user-activities` — enduser activity events, the raw input to adoption analysis (medium)
- [ ] `custom-field` — lookup describing the custom fields present on companies, endusers and licenses (medium)
- [ ] `task` — CSM task records for workload and playbook execution (medium)
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/canonical_descriptions.py
index 668fb54cefd5..31fd7378aa22 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/canonical_descriptions.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/canonical_descriptions.py
@@ -173,4 +173,84 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
"custom": "Custom properties set on the sale.",
},
},
+ "churn": {
+ "description": "A churn record logged against a company, with the reason the customer churned.",
+ "docs_url": "https://docs.planhat.com/developers/api/churn",
+ "columns": {
+ "_id": "The unique ID of the churn record.",
+ "companyId": "The ID of the company the churn record belongs to.",
+ "isChurn": "Whether the record represents a churn event.",
+ "churnReason": "The reason for the churn, for example product issues or missing features.",
+ "externalId": "Your own identifier for the churn record.",
+ "createDate": "When the churn record was created.",
+ "custom": "Custom properties set on the churn record, such as secondary churn reasons.",
+ },
+ },
+ "opportunities": {
+ "description": "A sales opportunity, usually a chance to expand an existing customer account.",
+ "docs_url": "https://docs.planhat.com/developers/api/opportunity",
+ "columns": {
+ "_id": "The unique ID of the opportunity.",
+ "title": "The title of the opportunity.",
+ "salesStage": "The sales stage of the opportunity.",
+ "status": "The status of the opportunity: active, won or lost.",
+ "companyId": "The ID of the company the opportunity belongs to.",
+ "companyName": "The name of the company the opportunity belongs to.",
+ "ownerId": "The ID of the Planhat user who owns the opportunity.",
+ "dealDate": "The deal date of the opportunity.",
+ "landingDate": "The landing date of the opportunity.",
+ "closeDate": "The close date of the opportunity.",
+ "_currency": "The currency code of the opportunity, for example USD.",
+ "mrr": "The monthly recurring value of the opportunity.",
+ "arr": "The annual recurring value of the opportunity.",
+ "nrr": "The non-recurring value of the opportunity.",
+ "contractLength": "The contract length in months.",
+ "stageHistory": "The history of stage changes on the opportunity.",
+ "externalId": "Your own identifier for the opportunity.",
+ "sourceId": "The ID of the opportunity in an integration such as Salesforce or HubSpot.",
+ "custom": "Custom properties set on the opportunity.",
+ },
+ },
+ "line_items": {
+ "description": "A subscription or fee on a deal. Revenue rolls up from line items to their deal and company.",
+ "docs_url": "https://docs.planhat.com/developers/api/line-item",
+ "columns": {
+ "_id": "The unique ID of the line item.",
+ "dealId": "The ID of the deal the line item belongs to.",
+ "dealName": "The name of the deal the line item belongs to.",
+ "companyId": "The ID of the company the line item belongs to.",
+ "companyName": "The name of the company the line item belongs to.",
+ "productId": "The ID of the product on the line item.",
+ "productName": "The name of the product on the line item.",
+ "productType": "The type of line item: subscription or fee.",
+ "fromDate": "When the line item starts.",
+ "toDate": "When the line item ends.",
+ "status": "The status of the line item: ongoing, renewed or lost.",
+ "fixedPeriod": "Whether the line item has a fixed end date.",
+ "autoRenews": "Whether the line item renews automatically.",
+ "length": "The length of the subscription period in months.",
+ "mrr": "The monthly recurring revenue of the line item.",
+ "arr": "The annual recurring revenue of the line item.",
+ "value": "The total value of the line item.",
+ "currency": "The currency of the line item.",
+ "revenueRecognized": "Whether the revenue of the line item is recognized.",
+ "renewalDate": "The expected renewal date.",
+ "externalId": "Your own identifier for the line item.",
+ "sourceId": "The ID of the line item in an integration such as Salesforce or HubSpot.",
+ },
+ },
+ "metrics": {
+ "description": "A time-series metric value (dimension data) recorded for a company or another model on a given day.",
+ "docs_url": "https://docs.planhat.com/developers/api/metrics",
+ "columns": {
+ "_id": "The unique ID of the metric value.",
+ "dimensionId": "The ID of the metric (dimension) the value belongs to.",
+ "time": "The day the value applies to.",
+ "value": "The raw numeric value of the metric.",
+ "model": "The model the value is recorded on: Company, EndUser, Asset or Project.",
+ "parentId": "The ID of the object the value is recorded on.",
+ "companyId": "The ID of the company the value belongs to.",
+ "companyName": "The name of the company the value belongs to.",
+ },
+ },
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/settings.py
index ea63d6784c54..215ef62d1f89 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/settings.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/settings.py
@@ -26,6 +26,12 @@ PLANHAT_ENDPOINTS: dict[str, PlanhatEndpointConfig] = {
"tickets": PlanhatEndpointConfig(name="tickets", path="/tickets"),
"invoices": PlanhatEndpointConfig(name="invoices", path="/invoices"),
"sales": PlanhatEndpointConfig(name="sales", path="/sales"),
+ "churn": PlanhatEndpointConfig(name="churn", path="/churn"),
+ "opportunities": PlanhatEndpointConfig(name="opportunities", path="/opportunities"),
+ "line_items": PlanhatEndpointConfig(name="line_items", path="/lineitems"),
+ # Planhat calls metrics "dimension data". The `from`/`to` day filters apply to the metric's `time`,
+ # not to when it was written, and backfilled values land on past days, so it stays full refresh too.
+ "metrics": PlanhatEndpointConfig(name="metrics", path="/dimensiondata"),
}
ENDPOINTS = tuple(PLANHAT_ENDPOINTS.keys())
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/source.py
index 76b45017bc28..555a84e0f0b4 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/source.py
@@ -56,7 +56,7 @@ class PlanhatSource(ResumableSource[PlanhatSourceConfig, PlanhatResumeConfig]):
releaseStatus=ReleaseStatus.GA,
caption="""Enter your Planhat API access token to pull your customer success data into the PostHog Data warehouse.
-You can create an API access token from a Private App under **Settings → Service Accounts** in [Planhat](https://app.planhat.com). The token is shown once, so copy it immediately. It grants read access to your companies, end users, users, licenses, assets, NPS responses, conversations, tickets, invoices, and sales.
+You can create an API access token from a Private App under **Settings → Service Accounts** in [Planhat](https://app.planhat.com). The token is shown once, so copy it immediately. It grants read access to your companies, end users, users, licenses, assets, NPS responses, conversations, tickets, invoices, sales, churn, opportunities, line items, and metrics.
""",
iconPath="/static/services/planhat.png",
docsUrl="https://posthog.com/docs/cdp/sources/planhat",
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/tests/test_planhat.py b/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/tests/test_planhat.py
index a3d3565c2bca..e2c9e574894a 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/tests/test_planhat.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/planhat/tests/test_planhat.py
@@ -108,6 +108,10 @@ class TestPlanhatSourceResponse:
("tickets", "/tickets"),
("invoices", "/invoices"),
("sales", "/sales"),
+ ("churn", "/churn"),
+ ("opportunities", "/opportunities"),
+ ("line_items", "/lineitems"),
+ ("metrics", "/dimensiondata"),
]
)
def test_source_response_shape(self, endpoint: str, expected_path: str) -> None: