feat(platform): implement convert organization to platform organization

[AnkitKmrGupta]

Type of Change

• Bugfix
• New feature
• Enhancement
• Refactoring
• Dependency updates
• Documentation
• CI/CD

Description

This pull request introduces support for Platform Organizations, enabling both:

1. Conversion of an existing Standard Organization to a Platform Organization, and
2. Direct creation of a Platform Organization during signup via signup_with_merchant_id.

Along with these flows, the PR updates organization and merchant account creation logic, validation rules, and data models to safely enable platform-specific capabilities.

Key Changes

Platform Organization Creation & Conversion

• Added new API request/response types:

  • ConvertOrganizationToPlatformRequest
  • ConvertOrganizationToPlatformResponse
    to support upgrading an existing organization to a Platform Organization, including event metric implementations.

• Implemented convert_organization_to_platform_organization, which:

  • Validates conversion eligibility
  • Updates the organization type to Platform
  • Creates the Platform Merchant
  • Returns updated organization and merchant identifiers.

• Extended signup_with_merchant_id to support direct creation of a Platform Organization during signup when platform creation is enabled and allowed.

• Updated OrganizationUpdate and OrganizationUpdateInternal to support the ConvertToPlatform variant, ensuring correct organization type transitions and platform merchant handling.

Data Model and Enum Updates

• Added OrganizationType to relevant API and database models to explicitly track whether an organization is STANDARD or PLATFORM.
• Replaced deprecated MerchantAccountRequestType with MerchantAccountType across multiple models.

Merchant Account Creation and Validation

• Tightened merchant creation rules:

  • Platform Organizations can own exactly one Platform Merchant
  • Standard Organizations can only create Standard Merchants
  • Platform Organizations can create Connected and Standard Merchants

• Added helpers to safely construct platform merchant creation requests.

User Signup and Platform Safeguards

• Added validation to ensure platform features are enabled before allowing platform organization creation.
• Restricted Platform Organization creation via signup_with_merchant_id in production environments unless explicitly permitted.
• Introduced a new InvalidPlatformOperation error variant for clearer error reporting on invalid platform-related actions.

Miscellaneous

• Refactored imports and removed unnecessary organization updates related to platform merchant IDs.
• Improved clarity and safety of platform-related flows across organization update and merchant creation logic.

These changes collectively enable safe creation and upgrading of Platform Organizations while enforcing strict business rules around merchant management and platform operations.

How did you test it?

Convert To Platform

Create Organization

curl --location 'http://localhost:8080/organization' \
--header 'Content-Type: application/json' \
--header 'api-key: test_admin' \
--data '{
  "organization_name": "Org_1",
  "organization_details": {
    "address": "123 Main Street",
    "city": "San Francisco",
    "country": "US"
  },
  "metadata": {
    "industry": "technology",
    "size": "medium"
  }
}

{
    "organization_id": "org_XpEBBGgsGEC1s86h9vHL",
    "organization_name": "Org_1",
    "organization_details": {
        "city": "San Francisco",
        "address": "123 Main Street",
        "country": "US"
    },
    "metadata": {
        "size": "medium",
        "industry": "technology"
    },
    "modified_at": "2026-01-13 07:13:00.765357",
    "created_at": "2026-01-13 07:13:00.76531",
    "organization_type": "standard"
}

Convert To Platform

curl --location 'http://localhost:8080/organization/org_XpEBBGgsGEC1s86h9vHL/convert_to_platform' \
--header 'Content-Type: application/json' \
--header 'api-key: test_admin' \
--data '{
  "platform_merchant_name": "platform_merchant"
}'

{
    "organization_id": "org_XpEBBGgsGEC1s86h9vHL",
    "organization_type": "platform",
    "platform_merchant_id": "platform_merchant"
}

Signup with merchant_id

curl --location 'http://localhost:8080/user/signup_with_merchant_id' \
--header 'Content-Type: application/json' \
--header 'api-key: test_admin' \
--data-raw '{
  "name": "John Doe",
  "email": "[email protected]",
  "password": "SecurePassword123!",
  "company_name": "platform_mercahant_1",
  "organization_type": "platform"
}

{
    "is_email_sent": true
}

Screenshots

Convert To Platform

Signup with merchant_id

Checklist

• I formatted the code cargo +nightly fmt --all
• I addressed lints thrown by cargo clippy
• I reviewed the submitted code
• I added unit tests for my changes where possible

[semanticdiff-com]

Review changes with  

Changed Files

File	Status
crates/router/src/routes/lock_utils.rs	79% smaller
crates/router/src/routes/admin.rs	62% smaller
crates/router/src/routes/app.rs	36% smaller
crates/router/src/core/user.rs	36% smaller
crates/router/src/core/admin.rs	11% smaller
crates/router/src/types/domain/user.rs	8% smaller
crates/api_models/src/events.rs	0% smaller
crates/api_models/src/organization.rs	0% smaller
crates/api_models/src/user.rs	0% smaller
crates/common_enums/src/enums/accounts.rs	0% smaller
crates/diesel_models/src/organization.rs	0% smaller
crates/hyperswitch_domain_models/src/merchant_account.rs	0% smaller
crates/router/src/core/errors/user.rs	0% smaller
crates/router/src/db/organization.rs	0% smaller
crates/router/src/types/api/admin.rs	0% smaller
crates/router_env/src/logger/types.rs	0% smaller

[apoorvdixit88]

Shouldn't it be MerchantAccountRequestType?

[apoorvdixit88]

Please check if we can move this functions to utils/helpers.