> ## Documentation Index
> Fetch the complete documentation index at: https://twigz.arqqin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform Admin

> Platform configuration and administrative functions

## Overview

Platform Admin API provides system-wide configuration management including commission rates, category-specific commissions, wallet/payout settings, location settings, and commission preview calculations.

**Location:** `convex/admins/platformAdmin.ts`

***

## Create Platform Config

Creates the initial platform configuration with default values optimized for the UAE market. Fails if an active configuration already exists.

<ParamField path="adminUserId" type="string" required>
  Admin user ID creating the configuration
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const configId = await convex.mutation(api.admins.platformAdmin.createInitialPlatformConfig, {
    adminUserId: "admin_123"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  "pc123456789"
  ```
</ResponseExample>

<Note>
  Default values: 5% commission rate, 2 AED fixed fee, 1 AED minimum commission, 50 AED maximum commission. Includes pre-configured category commissions for Food (4%), Groceries (3%), and Electronics (7%), plus store tier rates for basic/premium/enterprise.
</Note>

***

## Get Platform Config

Returns the current active platform configuration. Filters by `isActive: true` and `effectiveDate <= now`, returning the most recent match.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const config = await convex.query(api.admins.platformAdmin.getActivePlatformConfig);
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "_id": "pc123456789",
    "_creationTime": 1700000000000,
    "defaultCommissionRate": 0.05,
    "fixedFeePerOrder": 2.0,
    "minimumCommission": 1.0,
    "maximumCommission": 50.0,
    "categoryCommissions": [
      {
        "categoryId": "cat_food",
        "commissionRate": 0.04,
        "fixedFee": 1.5,
        "minimumCommission": 0.5
      }
    ],
    "storeTierCommissions": [
      {
        "tierName": "basic",
        "commissionRate": 0.05,
        "fixedFee": 2.0,
        "minimumCommission": 1.0
      }
    ],
    "walletSettings": {
      "minPayoutAmount": 100.0,
      "maxPayoutAmount": 50000.0,
      "payoutProcessingFee": 5.0,
      "pendingBalanceHoldDays": 3
    },
    "locationSettings": {
      "defaultSearchRadiusKm": 5.0,
      "maxSearchRadiusKm": 25.0
    },
    "isActive": true,
    "effectiveDate": 1700000000000
  }
  ```
</ResponseExample>

***

## Update Platform Config

Partially updates the active platform configuration. Only provided fields are updated; omitted fields remain unchanged.

<ParamField path="adminUserId" type="string" required>
  Admin user ID performing the update
</ParamField>

<ParamField path="configId" type="Id<'platformConfig'>" required>
  Configuration ID to update
</ParamField>

<ParamField path="defaultCommissionRate" type="number">
  Default commission rate (0 to 1, e.g. 0.05 = 5%)
</ParamField>

<ParamField path="fixedFeePerOrder" type="number">
  Fixed fee per order in AED (must be >= 0)
</ParamField>

<ParamField path="minimumCommission" type="number">
  Minimum commission per order in AED (must be >= 0)
</ParamField>

<ParamField path="maximumCommission" type="number">
  Maximum commission cap per order in AED (must be >= 0)
</ParamField>

<ParamField path="walletSettings" type="object">
  Partial wallet settings update. Only provided sub-fields are updated:

  * `minPayoutAmount` — Minimum payout amount in AED
  * `maxPayoutAmount` — Maximum payout amount in AED
  * `payoutProcessingFee` — Fee per payout in AED
  * `pendingBalanceHoldDays` — Days to hold pending balance before release
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  await convex.mutation(api.admins.platformAdmin.updatePlatformConfig, {
    adminUserId: "admin_123",
    configId: "pc123456789",
    defaultCommissionRate: 0.05,
    minimumCommission: 0.50,
    fixedFeePerOrder: 1.00,
    walletSettings: {
      minPayoutAmount: 50.0,
      pendingBalanceHoldDays: 5
    }
  });
  ```
</CodeGroup>

<Note>
  Platform configuration changes affect commission calculations system-wide. Commission rate must be between 0 and 1.
</Note>

***

## Add Category Commission

Adds or updates a category-specific commission rate. If the category already has a commission entry, it is replaced.

<ParamField path="adminUserId" type="string" required>
  Admin user ID performing the action
</ParamField>

<ParamField path="configId" type="Id<'platformConfig'>" required>
  Platform configuration ID
</ParamField>

<ParamField path="categoryId" type="Id<'categories'>" required>
  Category ID to set commission for
</ParamField>

<ParamField path="commissionRate" type="number" required>
  Commission rate for this category (0 to 1, e.g. 0.04 = 4%)
</ParamField>

<ParamField path="fixedFee" type="number">
  Fixed fee per order for this category in AED (overrides default)
</ParamField>

<ParamField path="minimumCommission" type="number">
  Minimum commission for this category in AED (overrides default)
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  await convex.mutation(api.admins.platformAdmin.addCategoryCommission, {
    adminUserId: "admin_123",
    configId: "pc123456789",
    categoryId: "cat_electronics",
    commissionRate: 0.07,
    fixedFee: 3.0,
    minimumCommission: 2.0
  });
  ```
</CodeGroup>

<Note>
  If a commission entry already exists for the specified category, it will be updated with the new values. Commission rate must be between 0 and 1.
</Note>

***

## Get Commission Preview

Calculates a commission preview for a hypothetical order. Uses the store's primary category to determine applicable commission rates, falling back to platform defaults.

<ParamField path="storeId" type="Id<'stores'>" required>
  Store ID to calculate commission for (determines category-based rates)
</ParamField>

<ParamField path="subtotal" type="number" required>
  Order subtotal in AED
</ParamField>

<ParamField path="deliveryFee" type="number" required>
  Delivery fee in AED
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const preview = await convex.query(api.admins.platformAdmin.getCommissionPreview, {
    storeId: "s123456789",
    subtotal: 100.00,
    deliveryFee: 10.00
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "subtotal": 100.00,
    "deliveryFee": 10.00,
    "totalAmount": 110.00,
    "platformCommission": 7.50,
    "storeEarnings": 102.50,
    "commissionRate": 0.05,
    "fixedFee": 2.0,
    "commissionBreakdown": {
      "percentageCommission": 5.50,
      "fixedFeeAmount": 2.0,
      "minimumApplied": false,
      "maximumApplied": false
    }
  }
  ```
</ResponseExample>

<Note>
  Commission is calculated as `(subtotal + deliveryFee) * commissionRate + fixedFee`, then clamped between the minimum and maximum commission values. The commission will never exceed the order total.
</Note>