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.

49.7 KB
Raw Blame
import json
from datetime import UTC, datetime, timedelta
from typing import Any, cast

from unittest.mock import MagicMock, patch

from django.utils import timezone

import jwt
import requests
from parameterized import parameterized
from requests import JSONDecodeError
from rest_framework import status

from posthog.models import OrganizationMembership, PersonalAPIKey, Team
from posthog.models.oauth import OAuthAccessToken, OAuthApplication
from posthog.models.organization_provisioning import OrganizationProvisioning
from posthog.models.project_secret_api_key import ProjectSecretAPIKey
from posthog.models.utils import generate_random_token_personal, hash_key_value
from posthog.rate_limit import BillingReadBurstRateThrottle

from ee.api.test.base import APILicensedTest
from ee.billing.grants import BillingEntitlement, EffectiveBillingGrants, entitlements_for

PERIOD_START = int(datetime(2026, 9, 1, tzinfo=UTC).timestamp())
PERIOD_END = int(datetime(2026, 10, 1, tzinfo=UTC).timestamp())

SUBSCRIPTION: dict[str, Any] = {
    "status": "ok",
    "customer_id": 42,
    "has_subscription": True,
    "billing_period": {"current_period_start": PERIOD_START, "current_period_end": PERIOD_END, "interval": "month"},
    "free_trial": {"active": False, "expires_at": None},
    "provider_customer_id": "cus_Q1x9v2AbCdEf",
    "has_active_subscription": True,
    "subscription_level": "paid",
    "billing_plan": "boost",
    "billing_provider": "posthog",
    "is_annual_plan_customer": False,
    "trial": {"id": 7, "type": "standard", "status": "active", "target": "paid", "expires_at": PERIOD_END},
    "discount_percent": 20,
    "discount_amount_usd": None,
    "amount_off_expires_at": None,
    "startup_program_label": "Startup",
    "startup_program_label_previous": None,
}

USAGE: dict[str, Any] = {
    "status": "ok",
    "customer_id": 42,
    "billing_period": {"current_period_start": PERIOD_START, "current_period_end": PERIOD_END, "interval": "month"},
    "usage_reported_through": "2026-09-14",
    "usage_summary": [
        {"usage_key": "events", "usage": 3120400, "limit": 5000000},
        {"usage_key": "recordings", "usage": 15000, "limit": 15000},
    ],
    "products": [
        {
            "kind": "product",
            "key": "product_analytics",
            "usage_key": "events",
            "current_usage": 3120400,
            "usage_limit": 5000000,
            "has_exceeded_limit": False,
            "usage_ratio": 0.62,
            "tier_usage": [{"up_to": 1000000, "current_usage": 1000000}],
            "addons": [],
        }
    ],
}

PRODUCTS: dict[str, Any] = {
    "status": "ok",
    "customer_id": 42,
    "products": [{"kind": "product", "key": "product_analytics", "name": "Product analytics", "addons": []}],
}


def _response(payload: dict, status_code: int = 200) -> MagicMock:
    response = MagicMock()
    response.status_code = status_code
    response.json.return_value = payload
    return response


class OrganizationBillingTestMixin(APILicensedTest):
    """Setup shared by the organization billing cases.

    It carries no cases of its own, and its name keeps pytest from collecting it, so the cases on
    the classes below run once each instead of once per subclass.
    """

    def setUp(self):
        super().setUp()
        self.organization_membership.level = OrganizationMembership.Level.OWNER
        self.organization_membership.save()
        owner_only = patch("ee.billing.grants._owner_only_billing_enabled", return_value=False)
        member_read = patch("ee.billing.grants._member_billing_usage_spend_read_access_enabled", return_value=False)
        # The viewset is behind a feature flag. It is on for the suite, and off in the one test
        # about the gate.
        api_flag = patch("posthog.permissions.posthog_feature_flag_enabled", return_value=True)
        self.owner_only = owner_only.start()
        self.member_read = member_read.start()
        # The patcher as well as the mock: a case that wants the real helper has to stop it.
        self.api_flag_patcher = api_flag
        self.api_flag = api_flag.start()
        self.addCleanup(owner_only.stop)
        self.addCleanup(member_read.stop)
        self.addCleanup(api_flag.stop)

    def _url(self, path: str) -> str:
        return f"/api/organizations/{self.organization.id}/billing/{path}"

    def _oauth_token(self, scope: str) -> str:
        app = OAuthApplication.objects.create(
            name="MCP client",
            client_id="test_billing_oauth_client",
            client_type=OAuthApplication.CLIENT_CONFIDENTIAL,
            authorization_grant_type=OAuthApplication.GRANT_AUTHORIZATION_CODE,
            redirect_uris="https://example.com/callback",
            algorithm="RS256",
            user=self.user,
        )
        token = OAuthAccessToken.objects.create(
            user=self.user,
            application=app,
            token="pha_test_billing_access_token",
            scope=scope,
            expires=timezone.now() + timedelta(hours=1),
        )
        self.client.logout()
        return token.token


class TestOrganizationBillingAPI(OrganizationBillingTestMixin, APILicensedTest):
    @patch("ee.billing.billing_manager.http_session.get")
    def test_endpoints_are_behind_the_feature_flag(self, mock_get):
        self.api_flag.return_value = False
        response = self.client.get(self._url("subscription/"))
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
        mock_get.assert_not_called()

        # A flag key nobody has created yet answers None, not False, and so does a flag service
        # that cannot be reached. The gate is the only thing between an unannounced API and the
        # open internet, so neither may read as a yes. Patched at the client rather than at the
        # helper above it, because the helper is where None becomes a refusal.
        self.api_flag_patcher.stop()
        self.addCleanup(self.api_flag_patcher.start)
        with patch("posthoganalytics.feature_enabled", return_value=None):
            response = self.client.get(self._url("subscription/"))
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
        mock_get.assert_not_called()

    @patch("ee.billing.billing_manager.http_session.get")
    def test_session_callers_are_throttled_too(self, mock_get):
        mock_get.return_value = _response(SUBSCRIPTION)
        with (
            patch("posthog.rate_limit.is_rate_limit_enabled", return_value=True),
            patch.object(BillingReadBurstRateThrottle, "rate", "1/minute"),
        ):
            first = self.client.get(self._url("subscription/"))
            second = self.client.get(self._url("subscription/"))
        self.assertEqual(
            (first.status_code, second.status_code), (status.HTTP_200_OK, status.HTTP_429_TOO_MANY_REQUESTS)
        )

    @patch("ee.billing.billing_manager.http_session.get")
    def test_subscription_is_reshaped_to_the_organization_contract(self, mock_get):
        mock_get.return_value = _response(SUBSCRIPTION)
        response = self.client.get(self._url("subscription/"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        body = response.json()
        self.assertNotIn("status", body)
        self.assertEqual(body["customer_id"], "cus_Q1x9v2AbCdEf")
        self.assertEqual(body["billing_provider"], "stripe")
        self.assertEqual(body["billing_period"]["current_period_start"], "2026-09-01T00:00:00Z")
        self.assertEqual(body["trial"]["expires_at"], "2026-10-01T00:00:00Z")
        self.assertNotIn("id", body["trial"])
        self.assertIsNone(body["free_trial_until"])
        self.assertTrue(body["billing_portal_url"].endswith("/api/billing/portal"))
        self.assertEqual(body["license"]["plan"], self.license.plan)
        self.assertNotIn("invoices_url", body)
        called_url = mock_get.call_args.args[0]
        self.assertTrue(called_url.endswith("/api/v2/billing/subscription/"), called_url)

    @parameterized.expand(
        [
            ("partner_billed", None, {"partner_name": "Example Partner"}),
            ("partner_billed_org_with_own_stripe_customer", "cus_example", None),
        ]
    )
    @patch("ee.billing.billing_manager.http_session.get")
    def test_subscription_names_the_partner_that_locks_billing(
        self, _name: str, customer_id: str | None, expected: dict[str, str] | None, mock_get: MagicMock
    ) -> None:
        mock_get.return_value = _response(SUBSCRIPTION)
        application = OAuthApplication.objects.create(
            name="Example Partner",
            client_id="example-partner",
            client_type=OAuthApplication.CLIENT_PUBLIC,
            authorization_grant_type=OAuthApplication.GRANT_AUTHORIZATION_CODE,
            redirect_uris="https://partner.example.com/callback",
            algorithm="RS256",
            is_provisioning_partner=True,
        )
        application.update_provisioning(pays_for_customers=True)
        OrganizationProvisioning.objects.create(
            organization=self.organization,
            partner=OrganizationProvisioning.Partner.PROVISIONING_API,
            application=application,
        )
        self.organization.customer_id = customer_id
        self.organization.save(update_fields=["customer_id"])

        response = self.client.get(self._url("subscription/"))

        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        self.assertEqual(response.json()["billing_managed_by_partner"], expected)

    @patch("ee.billing.billing_manager.http_session.get")
    def test_the_call_to_billing_carries_a_minted_token_with_the_grants(self, mock_get):
        mock_get.return_value = _response(SUBSCRIPTION)
        self.client.get(self._url("subscription/"))
        token = mock_get.call_args.kwargs["headers"]["Authorization"].removeprefix("Bearer ")
        self.assertEqual(jwt.get_unverified_header(token)["typ"], "at+jwt")
        claims = jwt.decode(token, options={"verify_signature": False})
        self.assertEqual(claims["scope"], "billing:read")
        self.assertEqual(claims["roles"], ["owner"])
        self.assertEqual(claims["entitlements"], entitlements_for(BillingEntitlement.FULL_ACCESS))
        self.assertEqual(claims["org_id"], str(self.organization.id))
        self.assertIsNone(claims["projects"])
        # The subject names the user by uuid, which never changes, and the analytics id rides beside it.
        self.assertEqual(claims["sub"], f"user:{self.user.uuid}")
        self.assertEqual(claims["distinct_id"], self.user.distinct_id)
        # And the token proves the license it names, not just that PostHog signed it.
        secret = self.license.key.partition("::")[2]
        assertion = jwt.decode(claims["license_assertion"], secret, algorithms=["HS256"], audience=claims["aud"])
        self.assertEqual(
            (assertion["sub"], assertion["org_id"], assertion["jti"], assertion["exp"]),
            (claims["license_id"], claims["org_id"], claims["jti"], claims["exp"]),
        )

    @patch("ee.billing.billing_manager.http_session.get")
    def test_a_user_without_a_distinct_id_keeps_a_subject_of_their_own(self, mock_get):
        mock_get.return_value = _response(SUBSCRIPTION)
        self.user.distinct_id = None
        self.user.save(update_fields=["distinct_id"])
        self.client.force_login(self.user)

        self.client.get(self._url("subscription/"))

        claims = jwt.decode(
            mock_get.call_args.kwargs["headers"]["Authorization"].removeprefix("Bearer "),
            options={"verify_signature": False},
        )
        self.assertEqual(claims["sub"], f"user:{self.user.uuid}")
        self.assertNotIn("distinct_id", claims)

    @patch("ee.billing.billing_manager.http_session.get")
    def test_current_alias_resolves_the_organization(self, mock_get):
        mock_get.return_value = _response(SUBSCRIPTION)
        response = self.client.get("/api/organizations/@current/billing/subscription/")
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)

    @patch("ee.billing.billing_manager.http_session.get")
    def test_usage_merges_todays_usage_and_the_quota_state(self, mock_get):
        mock_get.return_value = _response(USAGE)
        self.organization.usage = {
            "events": {"usage": 3120400, "limit": 5000000, "todays_usage": 120, "quota_limited_until": None},
            "recordings": {"usage": 15000, "limit": 15000, "todays_usage": 0, "quota_limited_until": PERIOD_END},
        }
        self.organization.save()
        response = self.client.get(self._url("usage/"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        body = response.json()
        rows = {row["usage_key"]: row for row in body["usage_summary"]}
        self.assertEqual(rows["events"]["todays_usage"], 120)
        self.assertIsNone(rows["events"]["quota_limited_until"])
        self.assertEqual(rows["recordings"]["quota_limited_until"], "2026-10-01T00:00:00Z")
        self.assertEqual(body["usage_reported_through"], "2026-09-14")
        # Today's 120 events are added to the product row, as the root billing read does.
        self.assertEqual(body["products"][0]["current_usage"], 3120520)
        self.assertEqual(body["products"][0]["usage_ratio"], 3120520 / 5000000)

    @patch("ee.billing.billing_manager.http_session.get")
    def test_member_reads_the_usage_status_and_never_the_organization_counts(self, mock_get):
        self.organization_membership.level = OrganizationMembership.Level.MEMBER
        self.organization_membership.save()
        self.organization.usage = {"recordings": {"usage": 15000, "limit": 15000, "quota_limited_until": PERIOD_END}}
        self.organization.save()
        response = self.client.get(self._url("usage/"))
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
        # The organization total needs full access, so the member read flag does not open it.
        self.member_read.return_value = True
        for path in ("usage/", "spend/"):
            self.assertEqual(self.client.get(self._url(path)).status_code, status.HTTP_403_FORBIDDEN, path)
        self.member_read.return_value = False
        mock_get.assert_not_called()

        mock_get.return_value = _response(USAGE_STATUS)
        response = self.client.get(self._url("usage/status/"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        self.assertTrue(mock_get.call_args.args[0].endswith("/api/v2/billing/usage/status/"))
        products = {p["key"]: p for p in response.json()["products"]}
        self.assertEqual(products["session_replay"]["quota_limited_until"], "2026-10-01T00:00:00Z")
        self.assertTrue(products["session_replay"]["has_exceeded_limit"])
        self.assertNotIn("current_usage", products["session_replay"])
        self.assertNotIn("usage_summary", response.json())

    @patch("ee.billing.billing_manager.http_session.get")
    def test_products_and_one_product(self, mock_get):
        mock_get.return_value = _response(PRODUCTS)
        response = self.client.get(self._url("products/?include_plans=true"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        self.assertEqual(response.json()["results"][0]["key"], "product_analytics")
        self.assertEqual(mock_get.call_args.kwargs["params"], {"include_plans": "true"})

        mock_get.return_value = _response({"status": "ok", "customer_id": 42, "product": PRODUCTS["products"][0]})
        response = self.client.get(self._url("products/product_analytics/"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        self.assertEqual(response.json()["key"], "product_analytics")
        self.assertTrue(mock_get.call_args.args[0].endswith("/api/v2/billing/products/product_analytics/"))

    @patch("ee.billing.billing_manager.http_session.get")
    def test_summary_reaches_billings_summary_and_not_a_product_named_summary(self, mock_get):
        product = {
            "key": "platform_and_support",
            "name": "Platform and support",
            "description": "SSO, permission management, and support.",
            "subscribed": None,
            "addons": [{"key": "teams", "name": "Teams", "description": "", "subscribed": False}],
            "features": [
                {"key": "sso_enforcement", "name": "Enforce SSO login", "included": True, "addon_keys": ["teams"]}
            ],
        }
        mock_get.return_value = _response({"status": "ok", "customer_id": 42, "products": [product]})
        response = self.client.get(self._url("products/summary/"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        self.assertEqual(response.json(), {"results": [product]})
        self.assertTrue(mock_get.call_args.args[0].endswith("/api/v2/billing/products/catalog/"))

    @patch("ee.billing.billing_manager.http_session.get")
    def test_billings_refusals_come_back_as_the_matching_errors(self, mock_get):
        mock_get.return_value = _response({"detail": "No product time_travel."}, 404)
        response = self.client.get(self._url("products/time_travel/"))
        self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND)
        mock_get.return_value = _response({"detail": "This resource needs the billing:full_access entitlement."}, 403)
        response = self.client.get(self._url("usage/"))
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)

        # A failure inside billing is not the caller's to fix, so it never reads as a bad request.
        mock_get.return_value = _response({"type": "server_error", "code": "response_invalid"}, 500)
        response = self.client.get(self._url("features/"))
        self.assertEqual(response.status_code, status.HTTP_502_BAD_GATEWAY)
        self.assertEqual(response.json()["code"], "billing_service_error")

        # A proxy in front of billing answers HTML, not JSON. The refusal still maps to itself
        # rather than becoming a 500 on the way through.
        not_json = MagicMock(status_code=403)
        not_json.json.side_effect = JSONDecodeError("Expecting value", "<html>", 0)
        mock_get.return_value = not_json
        response = self.client.get(self._url("usage/"))
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)

        # Billing's own body never reaches the caller. It renders through the same error envelope
        # this API uses, so re-raising it would name billing's "type" field as the offending
        # parameter and say nothing about the request.
        mock_get.return_value = _response(
            {"type": "validation_error", "code": "invalid", "attr": "breakdowns", "detail": "billing's own words"},
            400,
        )
        response = self.client.get(self._url("usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14"))
        body = response.json()
        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
        self.assertEqual(body["code"], "billing_query_rejected")
        self.assertNotIn("billing's own words", response.content.decode())

        # A code this API has guidance for keeps its own error, with its own wording.
        mock_get.return_value = _response({"type": "validation_error", "code": "usage_date_range_too_long"}, 400)
        response = self.client.get(self._url("usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14"))
        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
        self.assertEqual(response.json()["code"], "usage_date_range_too_long")

    @patch("ee.billing.billing_manager.http_session.get")
    def test_key_without_billing_scope_is_refused_before_billing_is_called(self, mock_get):
        raw = generate_random_token_personal()
        PersonalAPIKey.objects.create(
            user=self.user, label="x", secure_value=hash_key_value(raw), scopes=["insight:read"]
        )
        response = self.client.get(self._url("subscription/"), HTTP_AUTHORIZATION=f"Bearer {raw}")
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
        mock_get.assert_not_called()

    @patch("ee.billing.billing_manager.http_session.get")
    def test_oauth_token_with_billing_read_reads_like_a_key(self, mock_get):
        # The credential the MCP tools carry: an OAuth access token instead of a personal key.
        mock_get.return_value = _response(SUBSCRIPTION)
        bearer = self._oauth_token("billing:read")
        response = self.client.get(self._url("subscription/"), headers={"authorization": f"Bearer {bearer}"})
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        claims = jwt.decode(
            mock_get.call_args.kwargs["headers"]["Authorization"].removeprefix("Bearer "),
            options={"verify_signature": False},
        )
        self.assertEqual((claims["scope"], claims["roles"]), ("billing:read", ["owner"]))
        self.assertEqual(claims["entitlements"], entitlements_for(BillingEntitlement.FULL_ACCESS))

    @patch("ee.billing.billing_manager.http_session.get")
    def test_oauth_token_without_billing_scope_is_refused_before_billing_is_called(self, mock_get):
        bearer = self._oauth_token("insight:read")
        response = self.client.get(self._url("subscription/"), headers={"authorization": f"Bearer {bearer}"})
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
        mock_get.assert_not_called()

    @patch("ee.billing.billing_manager.http_session.get")
    def test_key_with_billing_read_reads_subscription(self, mock_get):
        mock_get.return_value = _response(SUBSCRIPTION)
        raw = generate_random_token_personal()
        PersonalAPIKey.objects.create(
            user=self.user, label="x", secure_value=hash_key_value(raw), scopes=["billing:read"]
        )
        response = self.client.get(self._url("subscription/"), HTTP_AUTHORIZATION=f"Bearer {raw}")
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)

    @patch("ee.billing.billing_manager.http_session.get")
    def test_non_member_is_refused(self, mock_get):
        self.organization_membership.delete()
        response = self.client.get(self._url("subscription/"))
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
        mock_get.assert_not_called()


USAGE_STATUS: dict[str, Any] = {
    "status": "ok",
    "customer_id": 42,
    "billing_period": USAGE["billing_period"],
    "usage_reported_through": "2026-09-14",
    "products": [
        {
            "kind": "product",
            "key": "product_analytics",
            "usage_key": "events",
            "usage_limit": 5000000,
            "has_exceeded_limit": False,
            "approaching_limit": False,
            "addons": [],
        },
        {
            "kind": "product",
            "key": "session_replay",
            "usage_key": "recordings",
            "usage_limit": 15000,
            "has_exceeded_limit": True,
            "approaching_limit": False,
            "addons": [],
        },
    ],
}

SPEND: dict[str, Any] = {
    "status": "ok",
    "customer_id": 42,
    "billing_period": {"current_period_start": PERIOD_START, "current_period_end": PERIOD_END, "interval": "month"},
    "usage_reported_through": "2026-09-14",
    "current_total_amount_usd": "212.40",
    "current_total_amount_usd_after_discount": "169.92",
    "products": [],
}
FORECAST = {**SPEND, "projected_total_amount_usd": "480.00", "computed_at": PERIOD_START}
SERIES: dict[str, Any] = {
    "status": "ok",
    "customer_id": 42,
    "results": [{"id": i, "label": f"s{i}", "data": [1.0], "dates": ["2026-09-01"]} for i in range(3)],
    "team_id_options": [1],
}


class TestOrganizationBillingSpendForecastAndSeries(OrganizationBillingTestMixin, APILicensedTest):
    @patch("ee.billing.billing_manager.http_session.get")
    def test_spend_and_forecast_are_reshaped(self, mock_get):
        mock_get.return_value = _response(SPEND)
        response = self.client.get(self._url("spend/"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        body = response.json()
        self.assertEqual(body["current_total_amount_usd"], "212.40")
        self.assertEqual(body["billing_period"]["current_period_end"], "2026-10-01T00:00:00Z")
        self.assertNotIn("status", body)
        mock_get.return_value = _response(FORECAST)
        response = self.client.get(self._url("forecast/"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        self.assertEqual(response.json()["computed_at"], "2026-09-01T00:00:00Z")

    @patch("ee.billing.billing_manager.http_session.get")
    def test_member_without_the_read_flag_is_refused_spend_before_billing_is_called(self, mock_get):
        self.organization_membership.level = OrganizationMembership.Level.MEMBER
        self.organization_membership.save()
        response = self.client.get(self._url("spend/"))
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
        response = self.client.get(self._url("forecast/"))
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
        mock_get.assert_not_called()

    @parameterized.expand([("usage",), ("spend",)])
    @patch("ee.billing.billing_manager.http_session.get")
    def test_timeseries_timeout_tells_the_person_to_ask_for_less(self, kind, mock_get):
        mock_get.side_effect = requests.Timeout()
        response = self.client.get(self._url(f"{kind}/timeseries/?start_date=2026-09-01&end_date=2026-09-14"))
        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST, response.content)
        self.assertEqual(response.json()["code"], "usage_query_timeout")

    @patch("ee.billing.billing_manager.http_session.get")
    def test_timeseries_pages_by_cursor_the_way_the_api_does(self, mock_get):
        mock_get.return_value = _response({**SERIES, "next": "c2", "total_count": 7})
        response = self.client.get(self._url("usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14&limit=2"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        body = response.json()
        sent = mock_get.call_args.kwargs["params"]
        # limit and cursor are the API's names. Billing hears page_size and after.
        self.assertEqual((sent.get("page_size"), "limit" in sent), (2, False))
        self.assertEqual((body["count"], body["previous"], len(body["results"])), (7, None, 3))
        self.assertTrue(
            body["next"].endswith(
                "/billing/usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14&limit=2&cursor=c2"
            ),
            body["next"],
        )

        # The second page's previous is the first page: the same request without a cursor.
        mock_get.return_value = _response({**SERIES, "next": "c3", "previous": "", "total_count": 7})
        response = self.client.get(
            self._url("usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14&limit=2&cursor=c2")
        )
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        sent = mock_get.call_args.kwargs["params"]
        self.assertEqual((sent.get("after"), "cursor" in sent), ("c2", False))
        body = response.json()
        self.assertTrue(
            body["previous"].endswith("/billing/usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14&limit=2"),
            body["previous"],
        )

        # Further in, previous carries the cursor that seeks to the page before.
        mock_get.return_value = _response({**SERIES, "previous": "c2", "total_count": 7})
        response = self.client.get(
            self._url("usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14&limit=2&cursor=c3")
        )
        body = response.json()
        self.assertTrue(body["previous"].endswith("&limit=2&cursor=c2"), body["previous"])
        # The last page has no next link.
        self.assertEqual((body["count"], body["next"]), (7, None))

        mock_get.return_value = _response(SERIES)
        response = self.client.get(self._url("usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14"))
        body = response.json()
        # An unpaged answer has no links and counts what it holds.
        self.assertEqual((body["count"], body["next"], body["previous"]), (3, None, None))

    def test_team_scoped_key_is_refused_on_organization_endpoints_like_everywhere_else(self):
        raw = generate_random_token_personal()
        PersonalAPIKey.objects.create(
            user=self.user,
            label="x",
            secure_value=hash_key_value(raw),
            scopes=["billing:read"],
            scoped_teams=[self.team.id],
        )
        response = self.client.get(
            self._url("spend/timeseries/?start_date=2026-09-01&end_date=2026-09-14"), HTTP_AUTHORIZATION=f"Bearer {raw}"
        )
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
        self.assertIn("scoped projects", response.json()["detail"])

    @patch("ee.billing.billing_manager.http_session.get")
    async def test_export_streams_billing_csv_with_project_names_written_in(self, mock_get):
        upstream = MagicMock()
        upstream.status_code = 200
        upstream.headers = {"Content-Type": "text/csv", "Content-Disposition": 'attachment; filename="usage.csv"'}
        upstream.iter_content.return_value = iter(
            [b"Product,Project,Project ID,Total\n", f"events,{self.team.id},{self.team.id},10\n".encode()]
        )
        mock_get.return_value = upstream
        await self.async_client.aforce_login(self.user)
        response = await self.async_client.get(
            self._url(
                "usage/export/?start_date=2026-09-01&end_date=2026-09-14&breakdowns=%5B%22type%22%2C%22team%22%5D"
            )
        )
        self.assertEqual(response.status_code, status.HTTP_200_OK, getattr(response, "content", b"")[:200])
        self.assertEqual(response["Content-Disposition"], 'attachment; filename="usage.csv"')
        body = b"".join([chunk async for chunk in cast(Any, response).streaming_content])
        self.assertEqual(
            body.decode(), f"Product,Project,Project ID,Total\nevents,{self.team.name},{self.team.id},10\n"
        )
        sent = mock_get.call_args
        self.assertTrue(sent.args[0].endswith("/api/v2/billing/usage/export/"), sent.args[0])
        self.assertTrue(sent.kwargs["stream"])
        self.assertNotIn("teams_map", sent.kwargs["params"])

    @patch("ee.billing.billing_manager.http_session.get")
    def test_member_without_the_read_flag_is_refused_the_export_before_billing_is_called(self, mock_get):
        self.organization_membership.level = OrganizationMembership.Level.MEMBER
        self.organization_membership.save()
        response = self.client.get(self._url("spend/export/?start_date=2026-09-01&end_date=2026-09-14"))
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
        mock_get.assert_not_called()

    @patch("ee.billing.billing_manager.http_session.get")
    def test_member_series_are_clipped_to_the_teams_they_can_see(self, mock_get):
        mock_get.return_value = _response(SERIES)
        self.organization_membership.level = OrganizationMembership.Level.MEMBER
        self.organization_membership.save()
        self.member_read.return_value = True
        with patch("ee.api.organization_billing.visible_team_ids", return_value=[self.team.id]):
            response = self.client.get(self._url("usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        sent = mock_get.call_args.kwargs["params"]
        token = mock_get.call_args.kwargs["headers"]["Authorization"].removeprefix("Bearer ")
        claims = jwt.decode(token, options={"verify_signature": False})
        # The filter names the projects even when the member sees every one, so a project deleted
        # since its usage was reported is never read. The token carries no list: its projects are
        # the credential's own scope, which this credential does not have.
        self.assertEqual((claims["projects"], sent["team_ids"]), (None, json.dumps([self.team.id])))
        with patch("ee.api.organization_billing.visible_team_ids", return_value=[]):
            response = self.client.get(self._url("usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14"))
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)

        # A credential scoped to two projects, held by someone who can see one of them: the filter
        # is the overlap. Neither the credential nor the visibility widens the other.
        other = Team.objects.create(organization=self.organization, name="Other")
        grants = EffectiveBillingGrants(
            sub=f"user:{self.user.uuid}",
            scope=["billing:read"],
            roles=["member"],
            entitlements=entitlements_for(BillingEntitlement.USAGE_READ),
            projects=sorted([self.team.id, other.id]),
        )
        with (
            patch("ee.api.organization_billing.effective_billing_grants", return_value=grants),
            patch("ee.api.organization_billing.visible_team_ids", return_value=[other.id]),
        ):
            response = self.client.get(self._url("usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        self.assertEqual(mock_get.call_args.kwargs["params"]["team_ids"], json.dumps([other.id]))

    @patch("ee.billing.billing_manager.http_session.get")
    def test_a_credential_scoped_to_no_project_is_refused_rather_than_widened(self, mock_get):
        # PostHog never mints an empty project list today, so this guards the shape rather than a
        # reachable path: an empty filter would read downstream as no filter at all.
        grants = EffectiveBillingGrants(
            sub=f"user:{self.user.distinct_id}",
            scope=["billing:read"],
            roles=["owner"],
            entitlements=entitlements_for(BillingEntitlement.FULL_ACCESS),
            projects=[],
        )
        with patch("ee.api.organization_billing.effective_billing_grants", return_value=grants):
            response = self.client.get(self._url("usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14"))
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
        mock_get.assert_not_called()

    @patch("ee.billing.billing_manager.http_session.get")
    def test_a_project_scoped_credential_is_refused_the_organization_summaries(self, mock_get):
        # These reads are organization figures, so there is nothing to clip them to. The refusal
        # happens here, which is also what keeps it from costing a call to billing.
        grants = EffectiveBillingGrants(
            sub=f"user:{self.user.uuid}",
            scope=["billing:read"],
            roles=["owner"],
            entitlements=entitlements_for(BillingEntitlement.FULL_ACCESS),
            projects=[self.team.id],
        )
        with patch("ee.api.organization_billing.effective_billing_grants", return_value=grants):
            for path in ("usage/", "spend/", "forecast/", "limits/", "invoices/"):
                response = self.client.get(self._url(path))
                self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN, path)
        mock_get.assert_not_called()

    @patch("ee.billing.billing_manager.http_session.get")
    def test_a_whole_organization_caller_may_name_a_project_the_organization_no_longer_has(self, mock_get):
        mock_get.return_value = _response(SERIES)
        response = self.client.get(
            self._url("usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14&team_ids=[999999]")
        )
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        self.assertEqual(mock_get.call_args.kwargs["params"]["team_ids"], json.dumps([999999]))
        # Below full access the filter is the caller's visible projects, which a deleted one is never in.
        self.organization_membership.level = OrganizationMembership.Level.MEMBER
        self.organization_membership.save()
        self.member_read.return_value = True
        with patch("ee.api.organization_billing.visible_team_ids", return_value=[self.team.id]):
            response = self.client.get(
                self._url("usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14&team_ids=[999999]")
            )
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)

    @patch("ee.billing.billing_manager.http_session.get")
    def test_a_caller_who_can_see_no_project_is_refused_rather_than_given_an_empty_list(self, mock_get):
        self.organization_membership.level = OrganizationMembership.Level.MEMBER
        self.organization_membership.save()
        self.member_read.return_value = True
        with patch("ee.api.organization_billing.visible_team_ids", return_value=[]):
            for path in ("projects/", "usage/timeseries/?start_date=2026-09-01&end_date=2026-09-14"):
                self.assertEqual(self.client.get(self._url(path)).status_code, status.HTTP_403_FORBIDDEN, path)
        self.member_read.return_value = False

    @patch("ee.billing.billing_manager.http_session.get")
    def test_projects_names_live_projects_and_marks_deleted_ones(self, mock_get):
        mock_get.return_value = _response({"results": [{"id": 424242}, {"id": self.team.id}]})
        response = self.client.get(self._url("projects/"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        self.assertEqual(
            response.json(),
            {
                "count": 2,
                "next": None,
                "previous": None,
                "results": [
                    {"id": self.team.id, "name": self.team.name, "deleted": False},
                    {"id": 424242, "name": None, "deleted": True},
                ],
            },
        )
        self.assertTrue(mock_get.call_args.args[0].endswith("/api/v2/billing/projects/"), mock_get.call_args.args[0])
        # A member's list is the projects they can see, so a deleted project is not offered to them.
        self.organization_membership.level = OrganizationMembership.Level.MEMBER
        self.organization_membership.save()
        self.member_read.return_value = True
        with patch("ee.api.organization_billing.visible_team_ids", return_value=[self.team.id]):
            response = self.client.get(self._url("projects/"))
        self.assertEqual([project["id"] for project in response.json()["results"]], [self.team.id])


INVOICES: dict[str, Any] = {
    "status": "ok",
    "customer_id": 42,
    "next": "bz0x",
    "previous": None,
    "results": [
        {
            "id": "in_1",
            "number": "A1-0007",
            "status": "paid",
            "currency": "usd",
            "subtotal": "412.50",
            "total": "330.00",
            "amount_due": "330.00",
            "amount_paid": "330.00",
            "period_start": PERIOD_START,
            "period_end": PERIOD_END,
            "created": PERIOD_START,
            "due_date": None,
        }
    ],
}
LIMITS: dict[str, Any] = {
    "status": "ok",
    "customer_id": 42,
    "results": [
        {
            "key": "product_analytics",
            "limit_usd": 500,
            "next_period_limit_usd": None,
            "spend_usd": "212.40",
            "reached": False,
        }
    ],
}


class TestOrganizationBillingInvoicesAndLimits(OrganizationBillingTestMixin, APILicensedTest):
    @patch("ee.billing.billing_manager.http_session.get")
    def test_invoices_carry_iso_dates_and_cursor_urls(self, mock_get):
        mock_get.return_value = _response(INVOICES)
        response = self.client.get(self._url("invoices/?limit=1&status=paid"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        body = response.json()
        self.assertEqual(body["results"][0]["period_start"], "2026-09-01T00:00:00Z")
        self.assertIsNone(body["results"][0]["due_date"])
        # The next link keeps the page size and filter of this request.
        self.assertTrue(body["next"].endswith("/billing/invoices/?limit=1&status=paid&cursor=bz0x"), body["next"])
        self.assertIsNone(body["previous"])
        self.assertEqual(mock_get.call_args.kwargs["params"], {"limit": 1, "status": "paid"})
        for query in ("limit=abc", "limit=0", "status=draft"):
            response = self.client.get(self._url(f"invoices/?{query}"))
            self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST, query)

    @patch("ee.api.organization_billing.fetch_invoice_document")
    @patch("ee.billing.billing_manager.http_session.get")
    async def test_invoice_content_streams_the_pdf_without_exposing_the_link(self, mock_billing_get, mock_upstream_get):
        mock_billing_get.return_value = _response(
            {"status": "ok", "customer_id": 42, "url": "https://pay.example/in_1/pdf"}
        )
        read_from_provider: list[bytes] = []

        def provider_chunks():
            for chunk in (b"%PDF-1.4", b"..."):
                read_from_provider.append(chunk)
                yield chunk

        upstream = MagicMock()
        upstream.status_code = 200
        upstream.iter_content.return_value = provider_chunks()
        mock_upstream_get.return_value = upstream
        await self.async_client.aforce_login(self.user)

        # The ASGI client, because that is how PostHog serves requests and where a synchronous
        # body is read whole before the first byte goes out.
        response = await self.async_client.get(self._url("invoices/in_1/content/"))
        self.assertEqual(response.status_code, status.HTTP_200_OK)
        self.assertEqual(response["Content-Type"], "application/pdf")
        self.assertEqual(response["Content-Disposition"], 'attachment; filename="in_1.pdf"')
        body = cast(Any, response).streaming_content.__aiter__()
        first = await body.__anext__()
        self.assertEqual((first, read_from_provider), (b"%PDF-1.4", [b"%PDF-1.4"]))
        self.assertEqual(first + b"".join([chunk async for chunk in body]), b"%PDF-1.4...")
        self.assertEqual(mock_upstream_get.call_args.args[0], "https://pay.example/in_1/pdf")
        upstream.close.assert_called_once()

    @patch("ee.api.organization_billing.fetch_invoice_document")
    @patch("ee.billing.billing_manager.http_session.get")
    def test_invoice_content_is_a_404_when_the_provider_has_no_document(self, mock_billing_get, mock_upstream_get):
        mock_billing_get.return_value = _response(
            {"status": "ok", "customer_id": 42, "url": "https://pay.example/in_1/pdf"}
        )
        upstream = MagicMock(status_code=404)
        mock_upstream_get.return_value = upstream
        response = self.client.get(self._url("invoices/in_1/content/"))
        self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND)
        self.assertEqual(response.json()["detail"], "No document for invoice in_1.")
        upstream.iter_content.assert_not_called()
        upstream.close.assert_called_once()

        # Billing can also answer without a url at all, which says the same thing.
        mock_billing_get.return_value = _response({"status": "ok", "customer_id": 42})
        response = self.client.get(self._url("invoices/in_1/content/"))
        self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND)
        self.assertEqual(response.json()["detail"], "No document for invoice in_1.")

    @patch("ee.billing.billing_manager.http_session.get")
    def test_limits_pass_through(self, mock_get):
        mock_get.return_value = _response(LIMITS)
        response = self.client.get(self._url("limits/"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        self.assertEqual(response.json()["results"][0]["reached"], False)

    @patch("ee.billing.billing_manager.http_session.get")
    def test_admin_under_owner_only_billing_is_refused_invoices_and_limits(self, mock_get):
        self.organization_membership.level = OrganizationMembership.Level.ADMIN
        self.organization_membership.save()
        self.owner_only.return_value = True
        for path in ("invoices/", "limits/", "invoices/in_1/content/"):
            response = self.client.get(self._url(path))
            self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN, path)
        mock_get.assert_not_called()


class TestProjectBillingAPI(OrganizationBillingTestMixin, APILicensedTest):
    def setUp(self):
        super().setUp()
        self.other_team = Team.objects.create(organization=self.organization, name="Other project")

    def _project_url(self, path: str) -> str:
        return f"/api/projects/{self.team.id}/billing/{path}"

    def _personal_key(self, scoped_teams: list[int] | None) -> dict[str, Any]:
        raw = generate_random_token_personal()
        PersonalAPIKey.objects.create(
            user=self.user,
            label="billing",
            secure_value=hash_key_value(raw),
            scopes=["billing:read"],
            scoped_teams=scoped_teams,
        )
        self.client.logout()
        return {"HTTP_AUTHORIZATION": f"Bearer {raw}"}

    def _project_secret_key(self, team: Team) -> dict[str, Any]:
        token = "phs_" + "a" * 35 + str(team.id)
        ProjectSecretAPIKey.objects.create(
            team=team,
            label="billing",
            mask_value="phs_...",
            secure_value=hash_key_value(token),
            scopes=["billing:read"],
        )
        self.client.logout()
        return {"HTTP_AUTHORIZATION": f"Bearer {token}"}

    def _credential(self, name: str) -> dict[str, Any]:
        if name == "session":
            return {}
        if name == "organization_oauth_token":
            return {"HTTP_AUTHORIZATION": f"Bearer {self._oauth_token('billing:read')}"}
        if name == "personal_key_for_this_project":
            return self._personal_key([self.team.id])
        if name == "personal_key_for_another_project":
            return self._personal_key([self.other_team.id])
        if name == "project_secret_key_for_this_project":
            return self._project_secret_key(self.team)
        return self._project_secret_key(self.other_team)

    @parameterized.expand(
        [
            ("session", True),
            ("organization_oauth_token", True),
            ("personal_key_for_this_project", True),
            ("personal_key_for_another_project", False),
            ("project_secret_key_for_this_project", True),
            ("project_secret_key_for_another_project", False),
        ]
    )
    @patch("ee.billing.billing_manager.http_session.get")
    def test_project_series_read_only_the_project_a_credential_covers(self, credential, allowed, mock_get):
        mock_get.return_value = _response(SERIES)
        headers = self._credential(credential)
        # A request naming another project still reads only the project in the path.
        response = self.client.get(
            self._project_url(
                f"spend/timeseries/?start_date=2026-09-01&end_date=2026-09-14&team_ids=%5B{self.other_team.id}%5D"
            ),
            **headers,
        )
        if not allowed:
            self.assertIn(response.status_code, (status.HTTP_403_FORBIDDEN, status.HTTP_404_NOT_FOUND))
            mock_get.assert_not_called()
            return
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        self.assertEqual(json.loads(mock_get.call_args.kwargs["params"]["team_ids"]), [self.team.id])

    @parameterized.expand([("usage",), ("spend",)])
    @patch("ee.billing.billing_manager.http_session.get")
    async def test_project_export_sends_billing_only_the_project_in_the_path(self, kind, mock_get):
        upstream = MagicMock()
        upstream.status_code = 200
        upstream.headers = {"Content-Type": "text/csv"}
        upstream.iter_content.return_value = iter([b"Product,Total\n"])
        mock_get.return_value = upstream
        await self.async_client.aforce_login(self.user)
        # A request naming another project still exports only the project in the path.
        response = await self.async_client.get(
            self._project_url(
                f"{kind}/export/?start_date=2026-09-01&end_date=2026-09-14&team_ids=%5B{self.other_team.id}%5D"
            )
        )
        self.assertEqual(response.status_code, status.HTTP_200_OK, getattr(response, "content", b"")[:200])
        sent = mock_get.call_args
        self.assertTrue(sent.args[0].endswith(f"/api/v2/billing/{kind}/export/"), sent.args[0])
        self.assertEqual(json.loads(sent.kwargs["params"]["team_ids"]), [self.team.id])

    @parameterized.expand([("billing_period_read", 0), ("usage_read", 1)])
    @patch("ee.billing.billing_manager.http_session.get")
    def test_project_usage_timeout_tells_the_person_to_ask_for_less(self, _name, timed_out_call, mock_get):
        answers: list[Any] = [_response(SUBSCRIPTION), _response(SERIES)]
        answers[timed_out_call] = requests.Timeout()
        mock_get.side_effect = answers
        response = self.client.get(self._project_url("usage/"))
        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST, response.content)
        self.assertEqual(response.json()["code"], "usage_query_timeout")

    @patch("ee.billing.billing_manager.http_session.get")
    def test_project_usage_sums_the_series_since_the_billing_period_began(self, mock_get):
        series = {
            **SERIES,
            "results": [
                {
                    "id": 0,
                    "label": "Events",
                    "data": [1.0, 2.0],
                    "dates": ["2026-09-01", "2026-09-02"],
                    "breakdown_type": "type",
                    "breakdown_value": "event_count_in_period",
                }
            ],
        }
        mock_get.side_effect = [_response(SUBSCRIPTION), _response(series)]
        response = self.client.get(self._project_url("usage/"))
        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
        self.assertEqual(
            response.json()["results"], [{"usage_key": "event_count_in_period", "name": "Events", "usage": 3.0}]
        )
        sent = mock_get.call_args.kwargs["params"]
        self.assertEqual((sent["start_date"], json.loads(sent["team_ids"])), ("2026-09-01", [self.team.id]))