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(warehouse): add gumroad emails, workflows, payouts and earnings tables (#121105)

Tom Owersa8c455e505f0
diff --git a/posthog/test/repo_invariants/dataclass_frozen_baseline.txt b/posthog/test/repo_invariants/dataclass_frozen_baseline.txt
index 19b89527d0f9..f7fe02618cd3 100644
--- a/posthog/test/repo_invariants/dataclass_frozen_baseline.txt
+++ b/posthog/test/repo_invariants/dataclass_frozen_baseline.txt
@@ -612,7 +612,6 @@
1 products/warehouse_sources/backend/temporal/data_imports/sources/guardian/guardian.py
1 products/warehouse_sources/backend/temporal/data_imports/sources/guardian/settings.py
1 products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/gumroad.py
-1 products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/settings.py
1 products/warehouse_sources/backend/temporal/data_imports/sources/guru/guru.py
1 products/warehouse_sources/backend/temporal/data_imports/sources/gusto/gusto.py
1 products/warehouse_sources/backend/temporal/data_imports/sources/gusto/settings.py
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 68ccda0c82df..8a3869615c70 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
@@ -5641,14 +5641,14 @@ Note: The Content API documents exactly five endpoints: content (/search), tags,
## Gumroad — gaps
-Today (8): `custom_fields`, `offer_codes`, `payouts`, `product_reviews`, `products`, `sales`, `subscribers`, `variant_categories`
+Today (13): `custom_fields`, `earnings`, `emails`, `offer_codes`, `payouts`, `product_reviews`, `products`, `sales`, `subscribers`, `upcoming_payouts`, `variant_categories`, `workflow_emails`, `workflows`
Diffed against: <https://raw.githubusercontent.com/antiwork/gumroad/main/app/javascript/pages/Public/Api.tsx>
-- [ ] `Earnings (GET /v2/earnings)` — reconcile annual net income, tax totals, fees, and affiliate credits with the Tax Center (high)
-- [ ] `Upcoming payouts (GET /v2/payouts/upcoming)` — forecast pending cash receipts and compare payable balances with settled payouts (medium)
-- [ ] `Emails (GET /v2/emails)` — analyze audience outreach, delivered recipient counts, publishing dates, and product targeting alongside sales (medium)
-- [ ] `Workflows (GET /v2/workflows; GET /v2/workflows/{id})` — compare automated email sequences, delivery statistics, and product targeting with subscriber and sales outcomes (medium)
+- [x] `Earnings (GET /v2/earnings)` — reconcile annual net income, tax totals, fees, and affiliate credits with the Tax Center (high)
+- [x] `Upcoming payouts (GET /v2/payouts/upcoming)` — forecast pending cash receipts and compare payable balances with settled payouts (medium)
+- [x] `Emails (GET /v2/emails)` — analyze audience outreach, delivered recipient counts, publishing dates, and product targeting alongside sales (medium)
+- [x] `Workflows (GET /v2/workflows; GET /v2/workflows/{id})` — compare automated email sequences, delivery statistics, and product targeting with subscriber and sales outcomes (medium)
Note: Read the current API page source, its endpoint modules, and shared response definitions from Gumroad's official repository. Product responses already include variant options, so separate variant reads add no missing collection. The existing payout stream excludes upcoming payouts, whose null identifiers need a different key. Earnings require US Tax Center access; email and workflow reads require additional scopes.
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/canonical_descriptions.py
index 813329621eaf..6e3f22b2055b 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/canonical_descriptions.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/canonical_descriptions.py
@@ -166,4 +166,99 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
"products": "Identifiers of the products the field is attached to.",
},
},
+ "emails": {
+ "description": "An audience email (post) you wrote to your followers, customers, or a product's buyers, in any state from draft to published.",
+ "docs_url": "https://gumroad.com/api#emails",
+ "columns": {
+ "id": "Unique identifier for the email.",
+ "subject": "Subject line.",
+ "message": "HTML body of the email.",
+ "audience_type": "Who the email targets: audience, seller (customers), follower, or product.",
+ "product_id": "Identifier of the targeted product, for product emails.",
+ "state": "Current state: draft, scheduled, or published.",
+ "published_at": "When the email was published.",
+ "scheduled_at": "When the email is scheduled to publish.",
+ "send_emails": "Whether the post is sent by email to its audience.",
+ "shown_on_profile": "Whether the post is shown on your profile.",
+ "audience_count": "Estimated audience size, when computed.",
+ "recipients_count": "Number of recipients the email was delivered to, once published.",
+ "url": "Public post URL, once published.",
+ "created_at": "When the email was created.",
+ "updated_at": "When the email was last updated.",
+ },
+ },
+ "workflows": {
+ "description": "An active automated email sequence that sends emails to buyers, followers, or members after a trigger.",
+ "docs_url": "https://gumroad.com/api#workflows",
+ "columns": {
+ "id": "Unique identifier for the workflow.",
+ "name": "Workflow name.",
+ "audience_type": "Who the workflow targets.",
+ "trigger": "Trigger override, such as member_cancellation, or null for the default audience trigger.",
+ "product_id": "Identifier of the targeted product, if any.",
+ "variant_id": "Identifier of the targeted variant, if any.",
+ "state": "Current state: draft or published.",
+ "published_at": "When the workflow was published.",
+ "first_published_at": "When the workflow was first published.",
+ "send_to_past_customers": "Whether new steps also send to earlier eligible recipients.",
+ "emails_count": "Number of active email steps in the workflow.",
+ "filters": "Active audience filters, such as purchase amount, date, or country limits.",
+ "created_at": "When the workflow was created.",
+ "updated_at": "When the workflow was last updated.",
+ },
+ },
+ "workflow_emails": {
+ "description": "One email step of a workflow, with its delay and delivery statistics.",
+ "docs_url": "https://gumroad.com/api#workflows",
+ "columns": {
+ "id": "Unique identifier for the workflow email.",
+ "workflow_id": "Identifier of the workflow the email belongs to.",
+ "subject": "Subject line.",
+ "message": "HTML body of the email.",
+ "audience_type": "Who the email targets.",
+ "product_id": "Identifier of the targeted product, if any.",
+ "state": "Current state: draft, scheduled, or published.",
+ "published_at": "When the email was published.",
+ "send_emails": "Whether this step sends an email.",
+ "delay": "Delay after the workflow trigger, as an amount and a unit (hour, day, week, or month).",
+ "sent_count": "Number of emails sent for this step.",
+ "open_count": "Number of unique opens for this step.",
+ "open_rate": "Unique opens as a percentage of sent emails. Null before any emails are sent.",
+ "click_count": "Number of unique clicks for this step.",
+ "click_rate": "Unique clicks as a percentage of sent emails. Null before any emails are sent.",
+ "created_at": "When the email step was created.",
+ "updated_at": "When the email step or its delay was last updated.",
+ },
+ },
+ "upcoming_payouts": {
+ "description": "A payout Gumroad expects to send on a future date, from your current unpaid balance. There are at most two at a time.",
+ "docs_url": "https://gumroad.com/api#payouts",
+ "columns": {
+ "id": "Always null, because the payout has not been created yet.",
+ "created_at": "Date the payout is scheduled to be sent.",
+ "amount": "Expected payout amount, as a decimal string in the payout currency.",
+ "currency": "ISO code of the payout currency.",
+ "status": "Payout status, usually payable.",
+ "processed_at": "Always null for an upcoming payout.",
+ "payment_processor": "Processor that will send the payout.",
+ "bank_account_visual": "Masked bank account the payout will be sent to.",
+ "paypal_email": "PayPal address the payout will be sent to.",
+ "sales": "Identifiers of the sales included in the payout.",
+ "refunded_sales": "Identifiers of the refunded sales included in the payout.",
+ "disputed_sales": "Identifiers of the disputed sales included in the payout.",
+ },
+ },
+ "earnings": {
+ "description": "Annual earnings summary for one tax year, matching the totals in the Gumroad Tax Center. Fully refunded sales are excluded.",
+ "docs_url": "https://gumroad.com/api#earnings",
+ "columns": {
+ "year": "Tax year the earnings cover.",
+ "currency": "Currency of the amounts. Always usd.",
+ "gross_cents": "Gross earnings in cents across all successful, not fully refunded sales.",
+ "fees_cents": "Gumroad fees in cents.",
+ "taxes_cents": "Taxes collected by Gumroad or by you, in cents.",
+ "affiliate_credit_cents": "Affiliate credit in cents.",
+ "net_cents": "Net earnings in cents: gross minus fees, taxes, and affiliate credit.",
+ },
+ },
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/gumroad.py b/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/gumroad.py
index 9dbe8a9c0179..141b7187c82b 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/gumroad.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/gumroad.py
@@ -1,5 +1,6 @@
import dataclasses
-from collections.abc import Callable, Iterable
+from collections.abc import Callable, Iterable, Iterator
+from datetime import UTC, datetime
from typing import Any, Optional, cast
import requests
@@ -29,6 +30,8 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.common.res
from products.warehouse_sources.backend.temporal.data_imports.sources.common.resumable import ResumableSourceManager
from products.warehouse_sources.backend.temporal.data_imports.sources.common.typings import SourceResponse
from products.warehouse_sources.backend.temporal.data_imports.sources.gumroad.settings import (
+ EARNINGS_ENDPOINT,
+ EARNINGS_FIRST_YEAR,
GUMROAD_BASE_URL,
GUMROAD_ENDPOINTS,
INCREMENTAL_START_PARAM,
@@ -148,6 +151,34 @@ def _make_source_response(
)
+def _earnings_rows(access_token: str) -> Iterator[dict[str, Any]]:
+ """Yield one annual earnings summary per tax year, newest first.
+
+ `/v2/earnings` takes a required `year` and answers 404 outside the seller's available years,
+ which run from the account's creation year through the previous calendar year. Walk back from
+ the current year and stop at the first 404 below that range.
+ """
+ current_year = datetime.now(UTC).year
+ found_year = False
+ with make_tracked_session(redact_values=(access_token,), capture=False, allow_redirects=False) as session:
+ for year in range(current_year, EARNINGS_FIRST_YEAR - 1, -1):
+ response = session.get(
+ f"{GUMROAD_BASE_URL}/v2/earnings",
+ headers={"Authorization": f"Bearer {access_token}", "Accept": "application/json"},
+ params={"year": str(year)},
+ timeout=REQUEST_TIMEOUT_SECONDS,
+ )
+ if response.status_code == 404:
+ # The current year is never available, and last year can still be unavailable while
+ # Gumroad's clock is behind UTC on New Year's Day.
+ if found_year or year < current_year - 1:
+ return
+ continue
+ response.raise_for_status()
+ found_year = True
+ yield {key: value for key, value in response.json().items() if key != "success"}
+
+
def gumroad_source(
access_token: str,
endpoint: str,
@@ -160,6 +191,9 @@ def gumroad_source(
) -> SourceResponse:
endpoint_config = GUMROAD_ENDPOINTS[endpoint]
+ if endpoint == EARNINGS_ENDPOINT:
+ return _make_source_response(endpoint_config, lambda: _earnings_rows(access_token))
+
if endpoint_config.fanout:
parent_config = GUMROAD_ENDPOINTS[endpoint_config.fanout.parent_name]
# Dependent resources don't currently support resume in the rest_source framework;
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/settings.py
index c2726bcc83e1..f83e1faba09c 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/settings.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/settings.py
@@ -1,4 +1,6 @@
-from dataclasses import dataclass, field
+from dataclasses import field
+
+from posthog.dataclasses import frozen
from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.fanout import (
DependentEndpointConfig,
@@ -21,8 +23,12 @@ PAGE_KEY_PARAM = "page_key"
# re-reads from midnight of the watermark's day. The merge dedupes those rows on the primary key.
INCREMENTAL_START_PARAM = "after"
+EARNINGS_ENDPOINT = "earnings"
+# Gumroad launched in 2011, so no account has a tax year before it.
+EARNINGS_FIRST_YEAR = 2011
+
-@dataclass
+@frozen
class GumroadEndpointConfig:
name: str
path: str
@@ -39,6 +45,8 @@ class GumroadEndpointConfig:
# Path probed to tell whether the token carries the OAuth scope this table needs.
permission_probe_path: str = "/v2/user"
required_scope: str = "view_public"
+ # Shown in place of the missing-scope message when the probe can fail for another reason too.
+ permission_error: str | None = None
# Every product-scoped table fans out over `/v2/products`, carrying the parent's `id` in as
@@ -147,6 +155,69 @@ GUMROAD_ENDPOINTS: dict[str, GumroadEndpointConfig] = {
fanout=_PRODUCT_FANOUT,
permission_probe_path="/v2/products",
),
+ "emails": GumroadEndpointConfig(
+ name="emails",
+ path="/v2/emails",
+ data_selector="emails",
+ primary_key=["id"],
+ # No server-side date filter on this endpoint — full refresh.
+ partition_key="created_at",
+ permission_probe_path="/v2/emails",
+ required_scope="edit_emails",
+ ),
+ "workflows": GumroadEndpointConfig(
+ name="workflows",
+ path="/v2/workflows",
+ data_selector="workflows",
+ primary_key=["id"],
+ paginated=False,
+ partition_key="created_at",
+ permission_probe_path="/v2/workflows",
+ required_scope="edit_emails",
+ ),
+ "workflow_emails": GumroadEndpointConfig(
+ name="workflow_emails",
+ # The list endpoint omits the email steps; only the per-workflow read carries them and
+ # their delivery statistics.
+ path="/v2/workflows/{workflow_id}",
+ data_selector="workflow.emails",
+ primary_key=["workflow_id", "id"],
+ paginated=False,
+ partition_key="created_at",
+ fanout=DependentEndpointConfig(
+ parent_name="workflows",
+ resolve_param="workflow_id",
+ resolve_field="id",
+ include_from_parent=["id"],
+ parent_field_renames={"id": "workflow_id"},
+ ),
+ permission_probe_path="/v2/workflows",
+ required_scope="edit_emails",
+ ),
+ "upcoming_payouts": GumroadEndpointConfig(
+ name="upcoming_payouts",
+ path="/v2/payouts/upcoming",
+ data_selector="payouts",
+ # Upcoming payouts have a null `id`; `created_at` is the scheduled payout date, and there
+ # is at most one upcoming payout per date.
+ primary_key=["created_at"],
+ paginated=False,
+ permission_probe_path="/v2/payouts",
+ required_scope="view_payouts",
+ ),
+ "earnings": GumroadEndpointConfig(
+ name="earnings",
+ # Read one tax year per request; see `_earnings_rows`.
+ path="/v2/earnings",
+ data_selector="",
+ primary_key=["year"],
+ paginated=False,
+ permission_probe_path="/v2/earnings",
+ required_scope="view_tax_data",
+ permission_error=(
+ "Earnings need the view_tax_data scope and a US-based Gumroad account with the Tax Center enabled."
+ ),
+ ),
}
ENDPOINTS = tuple(GUMROAD_ENDPOINTS)
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/source.py
index 134d60cb0f37..e0f5cd7b5c86 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/source.py
@@ -112,7 +112,8 @@ class GumroadSource(ResumableSource[GumroadSourceConfig, GumroadResumeConfig]):
results[name] = (
None
if probed[path]
- else f"Your Gumroad access token is missing the {endpoint_config.required_scope} scope."
+ else endpoint_config.permission_error
+ or f"Your Gumroad access token is missing the {endpoint_config.required_scope} scope."
)
return results
@@ -145,11 +146,12 @@ class GumroadSource(ResumableSource[GumroadSourceConfig, GumroadResumeConfig]):
category=DataWarehouseSourceCategory.E_COMMERCE,
label="Gumroad",
caption=(
- "Import sales, products, payouts, subscribers, reviews, offer codes, versions, and "
- "custom fields from your Gumroad account.\n\n"
+ "Import sales, products, payouts, subscribers, reviews, offer codes, versions, custom "
+ "fields, emails, workflows, and annual earnings from your Gumroad account.\n\n"
"Create an application under Settings > Advanced > Applications, then generate an "
"access token for it. The token needs the `view_sales`, `view_payouts`, and "
- "`view_public` scopes."
+ "`view_public` scopes. Emails and workflows also need `edit_emails`, and earnings need "
+ "`view_tax_data` and a US-based account."
),
docsUrl="https://posthog.com/docs/cdp/sources/gumroad",
iconPath="/static/services/gumroad.png",
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/tests/test_gumroad.py b/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/tests/test_gumroad.py
index 5270bbfe7de8..7604355ec402 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/tests/test_gumroad.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/tests/test_gumroad.py
@@ -2,6 +2,7 @@ from datetime import UTC, date, datetime
from typing import Any, cast
import pytest
+import time_machine
from unittest.mock import patch
import requests
@@ -151,6 +152,57 @@ class TestGumroadTransport:
assert result.rows == [{"id": "sale-1"}, {"id": "sale-2"}]
assert result.saved_states == [GumroadResumeConfig(page_key="cursor-3")]
+ @parameterized.expand(
+ [
+ (
+ "stops_at_first_unavailable_year_below_last_year",
+ [404, 200, 200, 404],
+ [2025, 2024],
+ None,
+ ),
+ # Gumroad's clock can still be in the previous year, so last year is not yet available.
+ ("skips_unavailable_last_year", [404, 404, 200, 404], [2024], None),
+ ("account_created_this_year", [404, 404, 404], [], None),
+ ("tax_center_disabled", [403], [], "403 Client Error: Forbidden for url"),
+ ]
+ )
+ @time_machine.travel(datetime(2026, 1, 1, 3, 0, tzinfo=UTC), tick=False)
+ def test_earnings_walks_back_through_available_tax_years(
+ self, _name, statuses, expected_years, expected_error
+ ) -> None:
+ script = [
+ ScriptedResponse(status=status, json={"success": True, "year": 2026 - index, "net_cents": 100})
+ if status == 200
+ else ScriptedResponse(status=status, json={"success": False})
+ for index, status in enumerate(statuses)
+ ]
+
+ result = self._driver().run("earnings", script)
+
+ assert result.params("year") == [str(2026 - index) for index in range(len(statuses))]
+ assert [row["year"] for row in result.rows] == expected_years
+ assert all("success" not in row for row in result.rows)
+ if expected_error is None:
+ assert result.raised is None
+ else:
+ assert expected_error in str(result.raised)
+
+ def test_workflow_emails_fan_out_reads_steps_from_each_workflow(self) -> None:
+ result = self._driver().run(
+ "workflow_emails",
+ [
+ ScriptedResponse(json={"success": True, "workflows": [{"id": "wf-1"}, {"id": "wf-2"}]}),
+ ScriptedResponse(
+ json={"success": True, "workflow": {"id": "wf-1", "emails": [{"id": "e-1", "sent_count": 3}]}}
+ ),
+ ScriptedResponse(json={"success": True, "workflow": {"id": "wf-2", "emails": []}}),
+ ],
+ )
+
+ assert result.raised is None
+ assert result.paths == ["/v2/workflows", "/v2/workflows/wf-1", "/v2/workflows/wf-2"]
+ assert result.rows == [{"id": "e-1", "sent_count": 3, "workflow_id": "wf-1"}]
+
@parameterized.expand(
[
(200, True, None),
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/tests/test_gumroad_source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/tests/test_gumroad_source.py
index be938f4b9b81..e5aec8723a1b 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/tests/test_gumroad_source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/gumroad/tests/test_gumroad_source.py
@@ -43,13 +43,15 @@ class TestGumroadSource:
def test_get_endpoint_permissions_reports_missing_scope_per_table(self, mock_probe: mock.MagicMock) -> None:
# A token can hold view_public without view_payouts, and the user needs to see which
# table that costs them rather than having source creation fail.
- mock_probe.side_effect = lambda _token, path: path != "/v2/payouts"
+ mock_probe.side_effect = lambda _token, path: path not in ("/v2/payouts", "/v2/earnings")
results = self.source.get_endpoint_permissions(
- self.config, self.team_id, ["sales", "payouts", "products", "offer_codes"]
+ self.config, self.team_id, ["sales", "payouts", "products", "offer_codes", "earnings"]
)
assert results["sales"] is None
assert results["products"] is None
assert results["offer_codes"] is None
assert results["payouts"] is not None and "view_payouts" in results["payouts"]
+ # A US-only Tax Center also denies earnings, so the message can't blame the scope alone.
+ assert results["earnings"] is not None and "Tax Center" in results["earnings"]