DaraMex Docs

Appearance

How to Enable Business Registration for an Agency ​

Trigger ​

Use this runbook when:

  • You need to open business self-registration for an agency for the first time.
  • An admin reports they cannot enable the registration toggle.
  • Users report they cannot complete the public business registration flow.

Prerequisites ​

Before enabling business registration, the following conditions must be true:

  1. The agency has at least one active, public plan. The system will refuse to enable the registration flag if no plans exist.
  2. You have the agency-admin role on the agency you are configuring.
  3. (Optional) The agency has an active platform subscription. Registration is allowed without one, but a warning will appear in the UI and backend logs.

Step 1 — Verify or Create an Active Plan ​

  1. Navigate to Settings → Plans in the agency panel (or use the Plans API).
  2. Confirm that at least one plan exists with:
    • isActive: true
    • isPublic: true
    • deleted_at: null (not soft-deleted)

If no such plan exists:

  • Create a new plan via the panel UI or via POST /plans/agency-plans.
  • Activate an existing plan via PATCH /plans/agency-plans/:id with { "isActive": true }.

Reference: Plans Catalog and Management

Step 2 — Check Registration Status ​

Call the registration status endpoint to understand the current state before making changes:

http
GET /organization/my/registration-status
Authorization: Bearer <access_token>

Expected response when ready to enable:

json
{
  "allowBusinessRegistration": false,
  "hasActivePlans": true,
  "userCount": 3,
  "userLimit": 10,
  "limitSource": "platform_plan"
}

If hasActivePlans is false, complete Step 1 first.

Step 3 — Enable the Registration Flag ​

Via Panel UI ​

  1. Navigate to Settings → Registro y Onboarding.
  2. Click the Registro público habilitado toggle.
  3. Wait for the loading spinner to disappear.
  4. Confirm a success toast appears and the toggle shows ON.

Via API ​

http
PATCH /organization/my
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "allowBusinessRegistration": true
}

Expected response: HTTP 200 OK with the updated organization object.

Step 4 — Verify Registration is Open ​

Test the public endpoint from the business registration flow:

http
POST /identity/auth/user/register/business
x-agency-id: <your-agency-id>
Content-Type: application/json

{
  "email": "test-verify@example.com",
  "password": "SecurePass123!",
  "firstName": "Test",
  "lastName": "User"
}

Expected: HTTP 201 Created (or HTTP 409 if that email already exists — that is correct behavior).

Troubleshooting ​

"No puedes habilitar el registro sin al menos un plan activo" ​

Error code: IDENTITY.CANNOT_ENABLE_REGISTRATION_WITHOUT_PLANS
HTTP status: 409 Conflict

Cause: The toggle was set to ON but the agency has zero active public plans.

Resolution:

  1. Go to Settings → Plans.
  2. Create or activate at least one plan (isActive: true, isPublic: true).
  3. Retry enabling the toggle.

"El registro público de negocios está deshabilitado para esta agencia" ​

Error code: IDENTITY.BUSINESS_REGISTRATION_DISABLED
HTTP status: 403 Forbidden

Cause: A user tried to register but allowBusinessRegistration is false.

Resolution: Complete the steps above to enable registration, or confirm the correct agency ID is being sent in the x-agency-id header.

"Esta agencia no tiene planes activos disponibles para nuevos negocios" ​

Error code: IDENTITY.NO_ACTIVE_AGENCY_PLANS
HTTP status: 409 Conflict

Cause: The flag is ON but all plans were deactivated or deleted after the flag was enabled. This state can occur if plans were soft-deleted by another admin.

Resolution:

  1. Create or reactivate a plan.
  2. The registration endpoint will start accepting requests automatically — no flag toggle required.

"Se ha alcanzado el límite de usuarios para esta agencia" ​

Error code: IDENTITY.USER_LIMIT_REACHED
HTTP status: 409 Conflict

Cause: The agency's active platform subscription has a USERS resource limit and the current user count equals or exceeds it.

Resolution options:

  • Contact the platform admin to upgrade the agency's subscription to a plan with a higher user limit or unlimited users (quantity === -1).
  • If the agency has users that should be removed, deactivate or delete stale accounts first.

Subscription warning banner in panel ​

Cause: limitSource === 'no_subscription' — the agency has no active platform subscription. Registration is currently allowed (gate 3 passes with no limit), but this is a billing risk.

Resolution: Contact the platform admin to assign an active subscription to the agency.

"No se puede desactivar o eliminar el último plan activo mientras el registro de negocios está habilitado" ​

Error code: PLANS.CANNOT_DEACTIVATE_LAST_PLAN_REGISTRATION_ENABLED
HTTP status: 409 Conflict

Cause: An admin tried to deactivate or delete the last active plan while the registration flag is ON. The system prevents this to avoid an inconsistent state (flag ON, no plans).

Resolution options:

  • Disable the registration flag first (PATCH /organization/my with { "allowBusinessRegistration": false }), then deactivate or delete the plan.
  • Create a second plan first, then deactivate the original one.