onboarding: Add separate submit for review endpoint

Yopi · Yopi · commit c0ba40ce5571 · 2026-04-08T10:49:34.000+02:00
We store the details and call the specific endpoint when the user is submitting their org for review.
This is hidden from the external API.
diff --git a/clients/apps/web/src/components/Settings/OrganizationProfileSettings.tsx b/clients/apps/web/src/components/Settings/OrganizationProfileSettings.tsx
@@ -1,6 +1,7 @@
 import { useAuth } from '@/hooks'
 import { useOrganizationKYC } from '@/hooks/queries/org'
 import { useUpdateOrganization } from '@/hooks/queries'
+import { api } from '@/utils/client'
 import { useAutoSave } from '@/hooks/useAutoSave'
 import { useURLValidation } from '@/hooks/useURLValidation'
 import { setValidationErrors } from '@/utils/api/errors'
@@ -640,13 +641,59 @@ const OrganizationProfileSettings: React.FC<
       return
     }
 
-    reset({
-      ...data,
-      default_presentment_currency:
-        data.default_presentment_currency as schemas['PresentmentCurrency'],
-      country: data.country as schemas['CountryAlpha2Input'] | undefined,
-      socials: [...(data.socials || []), ...emptySocials],
-    })
+    if (inKYCMode) {
+      const submitReviewResult = await api.POST(
+        '/v1/organizations/{id}/submit-review',
+        {
+          params: { path: { id: organization.id } },
+        },
+      )
+      const { data: submittedOrganization, error: submitError } =
+        submitReviewResult
+
+      if (submitError) {
+        const errorMessage = Array.isArray(submitError.detail)
+          ? submitError.detail[0]?.msg ||
+            'An error occurred while submitting the organization for review'
+          : typeof submitError.detail === 'string'
+            ? submitError.detail
+            : 'An error occurred while submitting the organization for review'
+
+        if (isValidationError(submitError.detail)) {
+          setValidationErrors(submitError.detail, setError)
+        } else {
+          setError('root', { message: errorMessage })
+        }
+
+        toast({
+          title: 'Review Submission Failed',
+          description: errorMessage,
+        })
+
+        return
+      }
+
+      reset({
+        ...submittedOrganization,
+        default_presentment_currency:
+          submittedOrganization.default_presentment_currency as schemas['PresentmentCurrency'],
+        country: submittedOrganization.country as
+          | schemas['CountryAlpha2Input']
+          | undefined,
+        socials: [...(submittedOrganization.socials || []), ...emptySocials],
+        details: cleanedBody.details,
+      })
+    }
+
+    if (!inKYCMode) {
+      reset({
+        ...data,
+        default_presentment_currency:
+          data.default_presentment_currency as schemas['PresentmentCurrency'],
+        country: data.country as schemas['CountryAlpha2Input'] | undefined,
+        socials: [...(data.socials || []), ...emptySocials],
+      })
+    }
 
     // Refresh the router to get the updated organization data from the server
     router.refresh()
diff --git a/clients/packages/client/src/v1.ts b/clients/packages/client/src/v1.ts
@@ -705,6 +705,28 @@ export interface paths {
     patch?: never
     trace?: never
   }
+  '/v1/organizations/{id}/submit-review': {
+    parameters: {
+      query?: never
+      header?: never
+      path?: never
+      cookie?: never
+    }
+    get?: never
+    put?: never
+    /**
+     * Submit Organization for Review
+     * @description Submit an organization's saved details for review.
+     *
+     *     **Scopes**: `organizations:write`
+     */
+    post: operations['organizations:submit_review']
+    delete?: never
+    options?: never
+    head?: never
+    patch?: never
+    trace?: never
+  }
   '/v1/organizations/{id}/account': {
     parameters: {
       query?: never
@@ -30666,6 +30688,46 @@ export interface operations {
       }
     }
   }
+  'organizations:submit_review': {
+    parameters: {
+      query?: never
+      header?: never
+      path: {
+        id: string
+      }
+      cookie?: never
+    }
+    requestBody?: never
+    responses: {
+      /** @description Organization submitted for review. */
+      200: {
+        headers: {
+          [name: string]: unknown
+        }
+        content: {
+          'application/json': components['schemas']['Organization']
+        }
+      }
+      /** @description Organization not found. */
+      404: {
+        headers: {
+          [name: string]: unknown
+        }
+        content: {
+          'application/json': components['schemas']['ResourceNotFound']
+        }
+      }
+      /** @description Validation Error */
+      422: {
+        headers: {
+          [name: string]: unknown
+        }
+        content: {
+          'application/json': components['schemas']['HTTPValidationError']
+        }
+      }
+    }
+  }
   'organizations:get_account': {
     parameters: {
       query?: never
diff --git a/server/polar/organization/endpoints.py b/server/polar/organization/endpoints.py
@@ -176,6 +176,30 @@ async def update(
     return await organization_service.update(session, organization, organization_update)
 
 
+@router.post(
+    "/{id}/submit-review",
+    response_model=OrganizationSchema,
+    summary="Submit Organization for Review",
+    responses={
+        200: {"description": "Organization submitted for review."},
+        404: OrganizationNotFound,
+    },
+    tags=[APITag.private],
+)
+async def submit_review(
+    id: OrganizationID,
+    auth_subject: auth.OrganizationsWrite,
+    session: AsyncSession = Depends(get_db_session),
+) -> Organization:
+    """Submit an organization's saved details for review."""
+    organization = await organization_service.get(session, auth_subject, id)
+
+    if organization is None:
+        raise ResourceNotFound()
+
+    return await organization_service.submit_for_review(session, organization)
+
+
 @router.delete(
     "/{id}",
     response_model=OrganizationDeletionResponse,
diff --git a/server/polar/organization/service.py b/server/polar/organization/service.py
@@ -1,3 +1,4 @@
+import builtins
 import uuid
 from collections.abc import Sequence
 from datetime import UTC, datetime
@@ -15,7 +16,12 @@
 from polar.config import Environment, settings
 from polar.customer.repository import CustomerRepository
 from polar.enums import InvoiceNumbering
-from polar.exceptions import NotPermitted, PolarError, PolarRequestValidationError
+from polar.exceptions import (
+    NotPermitted,
+    PolarError,
+    PolarRequestValidationError,
+    ValidationError,
+)
 from polar.integrations.loops.service import loops as loops_service
 from polar.integrations.plain.service import plain as plain_service
 from polar.kit.anonymization import anonymize_email_for_deletion, anonymize_for_deletion
@@ -332,23 +338,96 @@ async def update(
             },
         )
 
-        # Only store details once to avoid API overrides later w/o review
-        # We do allow initial details being set upon creation that will still require review,
-        # so upon creation we set details but not details_submitted_at
-        # so details_submitted_at effectively doubles as a "submit for review"
-        # timestamp, for now. We'll revisit this soon enough. @pieterbeulque
-        if not organization.details_submitted_at and update_schema.details:
+        if update_schema.details:
             organization.details = cast(
                 OrganizationDetails, update_schema.details.model_dump()
             )
+
+        organization = await repository.update(organization, update_dict=update_dict)
+
+        await self._after_update(session, organization)
+        return organization
+
+    def _validate_review_submission(
+        self, organization: Organization
+    ) -> builtins.list[ValidationError]:
+        errors: builtins.list[ValidationError] = []
+
+        if not organization.name or not organization.name.strip():
+            errors.append(
+                {
+                    "loc": ("body", "name"),
+                    "msg": "Organization name is required.",
+                    "type": "value_error",
+                    "input": organization.name,
+                }
+            )
+
+        if not organization.website:
+            errors.append(
+                {
+                    "loc": ("body", "website"),
+                    "msg": "Website is required.",
+                    "type": "value_error",
+                    "input": organization.website,
+                }
+            )
+
+        if not organization.email:
+            errors.append(
+                {
+                    "loc": ("body", "email"),
+                    "msg": "Support email is required.",
+                    "type": "value_error",
+                    "input": organization.email,
+                }
+            )
+
+        if not any(
+            social.get("url", "").strip() for social in (organization.socials or [])
+        ):
+            errors.append(
+                {
+                    "loc": ("body", "socials"),
+                    "msg": "At least one social media link is required.",
+                    "type": "value_error",
+                    "input": organization.socials,
+                }
+            )
+
+        product_description = (organization.details or {}).get("product_description")
+        if (
+            not isinstance(product_description, str)
+            or len(product_description.strip()) < 30
+        ):
+            errors.append(
+                {
+                    "loc": ("body", "details", "product_description"),
+                    "msg": "Please provide at least 30 characters.",
+                    "type": "value_error",
+                    "input": product_description,
+                }
+            )
+
+        return errors
+
+    async def submit_for_review(
+        self, session: AsyncSession, organization: Organization
+    ) -> Organization:
+        errors = self._validate_review_submission(organization)
+
+        if errors:
+            raise PolarRequestValidationError(errors)
+
+        if organization.details_submitted_at is None:
             organization.details_submitted_at = datetime.now(UTC)
             enqueue_job(
                 "organization_review.run_agent",
                 organization_id=organization.id,
                 context=ReviewContext.SUBMISSION,
             )
 
-        organization = await repository.update(organization, update_dict=update_dict)
+        session.add(organization)
 
         await self._after_update(session, organization)
         return organization
@@ -949,8 +1028,8 @@ async def get_ai_review(
     ) -> OrganizationReview | None:
         """Get the existing AI review for an organization, if any.
 
-        The actual AI review is now triggered asynchronously via a background
-        task when organization details are first submitted (see update()).
+        The actual AI review is triggered asynchronously via a background
+        task when organization details are submitted for review.
         """
         repository = OrganizationReviewRepository.from_session(session)
         return await repository.get_by_organization(organization.id)
diff --git a/server/tests/organization/test_endpoints.py b/server/tests/organization/test_endpoints.py
@@ -261,6 +261,77 @@ async def test_disable_seat_based_pricing_when_enabled(
 
         assert response.status_code == 422
 
+    @pytest.mark.auth
+    async def test_submit_for_review_requires_relevant_fields(
+        self,
+        client: AsyncClient,
+        organization: Organization,
+        user_organization: UserOrganization,
+    ) -> None:
+        update_response = await client.patch(
+            f"/v1/organizations/{organization.id}",
+            json={
+                "details": {
+                    "product_description": "Too short",
+                    "selling_categories": ["Software / SaaS"],
+                    "pricing_models": ["Subscription"],
+                    "switching": False,
+                }
+            },
+        )
+        assert update_response.status_code == 200
+
+        response = await client.post(
+            f"/v1/organizations/{organization.id}/submit-review"
+        )
+
+        assert response.status_code == 422
+        error_locations = {tuple(error["loc"]) for error in response.json()["detail"]}
+        assert ("body", "website") in error_locations
+        assert ("body", "email") in error_locations
+        assert ("body", "socials") in error_locations
+        assert ("body", "details", "product_description") in error_locations
+
+    @pytest.mark.auth
+    async def test_submit_for_review_valid(
+        self,
+        client: AsyncClient,
+        mocker: MockerFixture,
+        organization: Organization,
+        user_organization: UserOrganization,
+    ) -> None:
+        enqueue_job_mock = mocker.patch("polar.organization.service.enqueue_job")
+
+        update_response = await client.patch(
+            f"/v1/organizations/{organization.id}",
+            json={
+                "website": "https://example.com",
+                "email": "support@example.com",
+                "socials": [{"platform": "x", "url": "https://x.com/polar"}],
+                "details": {
+                    "product_description": "Subscription SaaS for software teams and agencies.",
+                    "selling_categories": ["Software / SaaS"],
+                    "pricing_models": ["Subscription"],
+                    "switching": False,
+                },
+            },
+        )
+        assert update_response.status_code == 200
+
+        response = await client.post(
+            f"/v1/organizations/{organization.id}/submit-review"
+        )
+
+        assert response.status_code == 200
+        assert response.json()["details_submitted_at"] is not None
+        enqueue_job_mock.assert_called_once()
+
+    @pytest.mark.auth
+    async def test_submit_for_review_not_existing(self, client: AsyncClient) -> None:
+        response = await client.post(f"/v1/organizations/{uuid.uuid4()}/submit-review")
+
+        assert response.status_code == 404
+
 
 @pytest.mark.asyncio
 class TestInviteOrganization:
diff --git a/server/tests/organization/test_service.py b/server/tests/organization/test_service.py
