refactor: modify starter plan to create cardless transaction

Author: Bharani0012

pyproject.toml

@@ -25,6 +25,7 @@ dependencies = [
     "networkx==3.4.2",
     "fake-useragent==1.5.1",
     "pyarrow==19.0.0",
+    "pycountry>=24.6.1,<25.0.0",
     "wikipedia==1.4.0",
     "qdrant-client==1.9.2",
     "weaviate-client==4.10.2",

src/backend/base/langflow/api/v1/billing.py

@@ -14,10 +14,16 @@
 from langflow.services.paddle.subscriptions import (
     ensure_paddle_customer_for_user,
     has_active_subscription,
+    start_trial_subscription,
 )
 
 router = APIRouter(tags=["Billing"], prefix="/billing")
 
+class StartTrialRequest(BaseModel):
+    plan_key: str
+    seats: int = 1
+    country: str
+    postal_code: str
 
 class EnsurePaddleCustomerRequest(BaseModel):
     email: str | None = None
@@ -114,3 +120,25 @@ async def list_paddle_prices():
     except Exception as exc: #noqa: BLE001
         logger.exception(f"Error fetching Paddle prices {exc}")
         raise HTTPException(status_code=500, detail="Internal server error") #noqa: B904
+
+@router.post("/start-trial")
+async def start_trial(
+    payload: StartTrialRequest,
+    current_user: CurrentActiveUser,
+) -> dict:
+    """Start a cardless trial subscription for first-time users."""
+    if not get_settings_service().auth_settings.CLERK_AUTH_ENABLED:
+        raise HTTPException(status_code=400, detail="Clerk auth not enabled")
+
+    try:
+        return await start_trial_subscription(
+            plan_key=payload.plan_key,
+            seats=payload.seats,
+            country=payload.country,
+            postal_code=payload.postal_code,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except Exception as exc:  #noqa: BLE001
+        logger.exception(f"Error starting trial subscription {exc}")
+        raise HTTPException(status_code=500, detail="Internal server error") from exc

src/backend/base/langflow/services/auth/clerk_metadata_constants.py

@@ -23,6 +23,10 @@
 PADDLE_CUSTOMER_ID_KEY = "paddle_customer_id"  # Paddle customer ID
 PADDLE_SUBSCRIPTION_ID_KEY = "paddle_subscription_id"  # Paddle subscription ID
 ORGANISATION_CREATED_BY_KEY = "organisation_created_by"  # Clerk user id of org creator/admin
+PADDLE_PLAN_KEY = "paddle_plan_key"  # Active plan key
+PADDLE_SUBSCRIPTION_STATUS_KEY = "paddle_subscription_status"  # Active subscription status
+PADDLE_TRIAL_END_KEY = "paddle_trial_end"  # Trial end timestamp
+PADDLE_SEATS_KEY = "paddle_seats"  # Active seat count
 
 # ============================================================================
 # Custom Data Keys (stored in Paddle customer custom_data)

src/backend/base/langflow/services/paddle/subscriptions.py

@@ -5,21 +5,28 @@
 import asyncio
 import re
 from typing import Any
+from uuid import UUID
 
 from lfx.log.logger import logger
 from paddle_billing import Client  #noqa: TCH002
-from paddle_billing.Entities.Shared import CustomData
+from paddle_billing.Entities.Shared import CountryCode, CustomData
 from paddle_billing.Resources.Customers.Operations import CreateCustomer, UpdateCustomer
+from paddle_billing.Resources.Addresses.Operations import CreateAddress
 
 from langflow.services.auth.clerk_metadata_constants import (
     ORGANISATION_CREATED_BY_KEY,
     PADDLE_CUSTOM_DATA_USER_ID_KEY,
     PADDLE_CUSTOMER_ID_KEY,
     PADDLE_SUBSCRIPTION_ID_KEY,
+    PADDLE_PLAN_KEY,
+    PADDLE_SEATS_KEY,
+    PADDLE_SUBSCRIPTION_STATUS_KEY,
+    PADDLE_TRIAL_END_KEY,
 )
 from langflow.services.auth.clerk_utils import (
     get_clerk_user_id_from_payload,
     get_email_from_clerk_payload,
+    get_org_id_from_clerk_payload,
     get_organisation_created_by_from_clerk_payload,
     get_paddle_customer_id_from_clerk_payload,
     get_paddle_subscription_id_from_clerk_payload,
@@ -281,6 +288,180 @@ def _find_customer() -> Any | None:
     return await asyncio.to_thread(_find_customer)
 
 
+async def start_trial_subscription(
+    *,
+    plan_key: str,
+    seats: int,
+    country: str,
+    postal_code: str,
+    client: Client | None = None,
+) -> dict[str, Any]:
+    if seats < 1:
+        msg = "seats must be at least 1"
+        raise ValueError(msg)
+
+    normalized_country = _normalize_country_for_paddle(country)
+    normalized_postal_code = postal_code.strip()
+    if not normalized_postal_code:
+        msg = "postal_code is required"
+        raise ValueError(msg)
+
+    paddle_client = client or get_paddle_client()
+    org_id = get_org_id_from_clerk_payload()
+    organisation_created_by = get_clerk_user_id_from_payload()
+
+    subscription_id = await get_paddle_subscription_id_from_clerk_payload()
+    if subscription_id:
+        msg = "subscription already exists for current user/session"
+        raise ValueError(msg)
+
+    customer_id = await ensure_paddle_customer_for_user(client=paddle_client)
+    if not customer_id:
+        msg = "unable to resolve paddle customer"
+        raise ValueError(msg)
+
+    from langflow.services.paddle.provisioning import get_paddle_prices
+
+    price_map = await get_paddle_prices(client=paddle_client)
+    price_id = price_map.get(plan_key)
+    if not price_id:
+        msg = f"no Paddle price mapped for plan_key={plan_key}"
+        raise ValueError(msg)
+
+    address_id = await _create_paddle_address_for_customer(
+        client=paddle_client,
+        customer_id=customer_id,
+        country_code=normalized_country,
+        postal_code=normalized_postal_code,
+    )
+
+    payload = {
+        "items": [{"price_id": price_id, "quantity": seats}],
+        "customer_id": customer_id,
+        "address_id": address_id,
+        "status": "billed",
+    }
+
+    transaction = await asyncio.to_thread(paddle_client.transactions.create, payload)
+    details = _extract_subscription_details_from_transaction(transaction)
+
+    await update_clerk_organization(
+        org_id=org_id,
+        public_metadata={
+            PADDLE_SUBSCRIPTION_ID_KEY: details["subscription_id"],
+            ORGANISATION_CREATED_BY_KEY: organisation_created_by,
+        },
+        max_allowed_members=seats,
+    )
+
+    await update_clerk_user_metadata(
+        clerk_user_id=organisation_created_by,
+        public_metadata={
+            PADDLE_SUBSCRIPTION_ID_KEY: details["subscription_id"],
+            PADDLE_PLAN_KEY: plan_key,
+            PADDLE_SUBSCRIPTION_STATUS_KEY: details["status"],
+            PADDLE_TRIAL_END_KEY: details["trial_end"],
+            PADDLE_SEATS_KEY: seats,
+        },
+    )
+
+    return {
+        "subscription_id": details["subscription_id"],
+        "status": details["status"],
+        "trial_end": details["trial_end"],
+        "plan_key": plan_key,
+        "seats": seats,
+    }
+
+
+def _normalize_country_for_paddle(country: str) -> CountryCode:
+    value = country.strip()
+    if not value:
+        raise ValueError("country is required")
+
+    try:
+        import pycountry
+        # try uppercase first (for ISO alpha-2)
+        result = pycountry.countries.lookup(value.upper())
+        iso2 = result.alpha_2.upper()
+        logger.info(f"Normalized country '{value}' to ISO2 code: {iso2}")
+        return CountryCode(iso2)
+
+    except LookupError:
+        raise ValueError(f"invalid or unsupported country: {country}")
+
+
+def _extract_address_id(address: Any) -> str:
+    address_id = getattr(address, "id", None)
+    if isinstance(address_id, UUID):
+        return str(address_id)
+    if isinstance(address_id, str) and address_id.strip():
+        return address_id.strip()
+
+    data = _normalize_custom_data(getattr(address, "data", None))
+    nested_id = data.get("id") if isinstance(data, dict) else None
+    if isinstance(nested_id, UUID):
+        return str(nested_id)
+    if isinstance(nested_id, str) and nested_id.strip():
+        return nested_id.strip()
+
+    msg = "Paddle address response missing id"
+    raise ValueError(msg)
+
+
+async def _create_paddle_address_for_customer(
+    *,
+    client: Client,
+    customer_id: str,
+    country_code: CountryCode,
+    postal_code: str,
+) -> str:
+
+    operation = CreateAddress(
+        country_code=country_code,
+        postal_code=postal_code,
+    )
+
+    address = await asyncio.to_thread(
+        client.addresses.create,
+        customer_id,
+        operation,
+    )
+
+    logger.info(f"Created Paddle address for customer {customer_id}: {address}")
+
+    return _extract_address_id(address)
+
+
+def _extract_subscription_details_from_transaction(transaction: Any) -> dict[str, str]:
+    data = _normalize_custom_data(getattr(transaction, "data", None)) or transaction
+    if not isinstance(data, dict):
+        data = {}
+
+    subscription_id = (
+        data.get("subscription_id")
+        or _normalize_custom_data(data.get("subscription", None)).get("id")
+    )
+    status = data.get("status") or _normalize_custom_data(data.get("subscription", None)).get("status")
+    trial_end = (
+        data.get("next_billed_at")
+        or _normalize_custom_data(data.get("subscription", None)).get("next_billed_at")
+    )
+
+    if not isinstance(subscription_id, str) or not subscription_id.strip():
+        msg = "Paddle transaction response missing subscription_id"
+        raise ValueError(msg)
+
+    normalized_status = str(status).strip() if status else "trialing"
+    normalized_trial_end = str(trial_end).strip() if trial_end else ""
+
+    return {
+        "subscription_id": subscription_id.strip(),
+        "status": normalized_status,
+        "trial_end": normalized_trial_end,
+    }
+
+
 async def _sync_paddle_customer_metadata(
     *,
     client: Client,

src/backend/base/pyproject.toml

@@ -92,6 +92,7 @@ dependencies = [
     "langchain-ibm>=0.3.8,<1.0.0",
     "trustcall>=0.0.38,<1.0.0",
     "langchain-chroma>=0.1.4,<1.0.0",
+    "pycountry>=24.6.1,<25.0.0",
 ]
 
 [dependency-groups]

src/frontend/src/controllers/API/helpers/constants.ts

@@ -33,6 +33,7 @@ export const URLs = {
   KNOWLEDGE_BASES: `knowledge_bases`,
   BILLING_ACCESS: `billing/org-access`,
   GET_PADDLE_PRICES: `billing/paddle-prices`,
+  START_TRIAL: `billing/start-trial`,
 } as const;
 
 // IMPORTANT: FOLDERS endpoint now points to 'projects' for backward compatibility