Skip to main content

​
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.
​
adminUserId
string
required
Admin user ID creating the configuration
const configId = await convex.mutation(api.admins.platformAdmin.createInitialPlatformConfig, {
  adminUserId: "admin_123"
});

"pc123456789"
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.

​
Get Platform Config

Returns the current active platform configuration. Filters by isActive: true and effectiveDate <= now, returning the most recent match. 
const config = await convex.query(api.admins.platformAdmin.getActivePlatformConfig);

{
  "_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
}

​
Update Platform Config

Partially updates the active platform configuration. Only provided fields are updated; omitted fields remain unchanged.
​
adminUserId
string
required
Admin user ID performing the update
​
configId
Id<'platformConfig'>
required
Configuration ID to update
​
defaultCommissionRate
number
Default commission rate (0 to 1, e.g. 0.05 = 5%)
​
fixedFeePerOrder
number
Fixed fee per order in AED (must be >= 0)
​
minimumCommission
number
Minimum commission per order in AED (must be >= 0)
​
maximumCommission
number
Maximum commission cap per order in AED (must be >= 0)
​
walletSettings
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
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
  }
});
Platform configuration changes affect commission calculations system-wide. Commission rate must be between 0 and 1.

​
Add Category Commission

Adds or updates a category-specific commission rate. If the category already has a commission entry, it is replaced.
​
adminUserId
string
required
Admin user ID performing the action
​
configId
Id<'platformConfig'>
required
Platform configuration ID
​
categoryId
Id<'categories'>
required
Category ID to set commission for
​
commissionRate
number
required
Commission rate for this category (0 to 1, e.g. 0.04 = 4%)
​
fixedFee
number
Fixed fee per order for this category in AED (overrides default)
​
minimumCommission
number
Minimum commission for this category in AED (overrides default)
await convex.mutation(api.admins.platformAdmin.addCategoryCommission, {
  adminUserId: "admin_123",
  configId: "pc123456789",
  categoryId: "cat_electronics",
  commissionRate: 0.07,
  fixedFee: 3.0,
  minimumCommission: 2.0
});
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.

​
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.
​
storeId
Id<'stores'>
required
Store ID to calculate commission for (determines category-based rates)
​
subtotal
number
required
Order subtotal in AED
​
deliveryFee
number
required
Delivery fee in AED
const preview = await convex.query(api.admins.platformAdmin.getCommissionPreview, {
  storeId: "s123456789",
  subtotal: 100.00,
  deliveryFee: 10.00
});

{
  "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
  }
}
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.