Skip to main content

​
Overview

Store Onboarding API provides administrative functions for creating and managing stores, products, store categories, and delivery zones on behalf of store owners. These are admin-only mutations used during the onboarding flow or for ongoing store management. Location: convex/admins/storeOnboarding.ts

​
Admin Create Store

Creates a new store with optional auto-approval. When auto-approved, the store is immediately set to active and a wallet is initialized. Increments the storeCount on the assigned primary category.
​
name
string
required
Store name
​
nameArabic
string
Store name in Arabic
​
description
string
Store description
​
primaryCategory
Id<'categories'>
required
Primary category ID for the store
​
ownerUserId
string
Owner’s Clerk user ID. Defaults to "admin_managed" if not provided.
​
ownerName
string
required
Store owner’s full name
​
phoneNumber
string
required
Store owner’s phone number
​
email
string
Store contact email
​
logoId
Id<'_storage'>
Storage ID for the store logo image
​
coverImageId
Id<'_storage'>
Storage ID for the store cover/banner image
​
tradeLicenseId
Id<'_storage'>
Storage ID for the trade license document
​
autoApprove
boolean
If true, store is created with approved status, isActive: true, and a wallet is initialized automatically
​
settings
object
Store settings:
  • deliveryEnabled — Whether delivery is enabled
  • pickupEnabled — Whether pickup is enabled
  • allowsReturns — Whether returns are accepted
  • returnWindowDays — Return window in days
​
bankAccount
object
Bank account details:
  • IBAN — Bank IBAN number
  • bankName — Bank name
  • bankId — Bank ID reference
  • accountHolderName — Account holder name
​
address
object
Store address:
  • fullAddress — Full address string
  • city — City ID
  • area — Area ID
  • flatVilaNumber — Flat/villa number
  • buildingNameNumber — Building name or number
  • landmark — Nearby landmark
  • latitude — Latitude coordinate
  • longitude — Longitude coordinate
const storeId = await convex.mutation(api.admins.storeOnboarding.adminCreateStore, {
  name: "Pizza Palace",
  nameArabic: "قصر البيتزا",
  description: "Best pizza in town",
  primaryCategory: "cat_food",
  ownerName: "Ahmed Ali",
  phoneNumber: "+971501234567",
  email: "ahmed@pizzapalace.ae",
  autoApprove: true,
  settings: {
    deliveryEnabled: true,
    pickupEnabled: true,
    allowsReturns: false
  },
  bankAccount: {
    IBAN: "AE070331234567890123456",
    bankName: "Emirates NBD",
    accountHolderName: "Ahmed Ali"
  },
  address: {
    fullAddress: "Building 5, Downtown Dubai",
    city: "city_dubai",
    area: "area_downtown"
  }
});

"s123456789"

​
Admin Update Store

Updates an existing store’s fields. Only provided fields are updated. If primaryCategory changes, the denormalized storeCount on both old and new categories is updated.
​
storeId
Id<'stores'>
required
Store ID to update
​
name
string
Updated store name
​
nameArabic
string
Updated store name in Arabic
​
description
string
Updated description
​
primaryCategory
Id<'categories'>
Updated primary category (triggers counter updates)
​
ownerUserId
string
Updated owner user ID
​
ownerName
string
Updated owner name
​
phoneNumber
string
Updated phone number
​
email
string
Updated email
​
logoId
Id<'_storage'>
Updated logo storage ID
​
coverImageId
Id<'_storage'>
Updated cover image storage ID
​
tradeLicenseId
Id<'_storage'>
Updated trade license storage ID
​
settings
object
Updated store settings (same structure as create)
​
bankAccount
object
Updated bank account details (same structure as create)
​
address
object
Updated store address (same structure as create)
const storeId = await convex.mutation(api.admins.storeOnboarding.adminUpdateStore, {
  storeId: "s123456789",
  name: "Pizza Palace Premium",
  description: "Premium pizza experience",
  settings: {
    deliveryEnabled: true,
    pickupEnabled: true,
    allowsReturns: true,
    returnWindowDays: 7
  }
});

​
Admin Create Product

Creates a product for a store. Validates that the product category is a child of the store’s primary category.
​
storeId
Id<'stores'>
required
Store ID to add the product to
​
name
string
required
Product name
​
description
string
Product description
​
category
Id<'categories'>
required
Product category ID (must be a child of the store’s primary category)
​
price
number
required
Product price in AED
​
cost
number
Product cost (for profit tracking)
​
stock
number
Available stock quantity
​
stockAlert
number
Low stock alert threshold
​
prepTime
number
Preparation time value
​
prepTimeUnit
string
Preparation time unit: minutes, hours, or days
​
isActive
boolean
required
Whether the product is active and visible
​
primaryImage
Id<'_storage'>
required
Storage ID for the primary product image
​
images
Id<'_storage'>[]
Additional product image storage IDs
​
isReturnable
boolean
Whether the product can be returned
​
isDeliveryEnabled
boolean
Whether delivery is available for this product
​
isPickupEnabled
boolean
Whether pickup is available for this product
const productId = await convex.mutation(api.admins.storeOnboarding.adminCreateProduct, {
  storeId: "s123456789",
  name: "Margherita Pizza",
  description: "Classic margherita with fresh mozzarella",
  category: "cat_pizza",
  price: 45.00,
  cost: 15.00,
  stock: 100,
  stockAlert: 10,
  prepTime: 20,
  prepTimeUnit: "minutes",
  isActive: true,
  primaryImage: "img_storage_id",
  isDeliveryEnabled: true,
  isPickupEnabled: true
});

​
Admin Update Product

Updates an existing product. Only provided fields are modified.
​
productId
Id<'products'>
required
Product ID to update
​
name
string
Updated product name
​
description
string
Updated description
​
category
Id<'categories'>
Updated category
​
price
number
Updated price
​
cost
number
Updated cost
​
stock
number
Updated stock quantity
​
stockAlert
number
Updated stock alert threshold
​
prepTime
number
Updated preparation time
​
prepTimeUnit
string
Updated preparation time unit: minutes, hours, or days
​
isActive
boolean
Updated active status
​
primaryImage
Id<'_storage'>
Updated primary image storage ID
​
images
Id<'_storage'>[]
Updated additional images
​
isReturnable
boolean
Updated returnable flag
​
isDeliveryEnabled
boolean
Updated delivery flag
​
isPickupEnabled
boolean
Updated pickup flag
const productId = await convex.mutation(api.admins.storeOnboarding.adminUpdateProduct, {
  productId: "prod_123456789",
  price: 50.00,
  stock: 200,
  isActive: true
});

​
Admin Delete Product

Permanently deletes a product from the database.
​
productId
Id<'products'>
required
Product ID to delete
const result = await convex.mutation(api.admins.storeOnboarding.adminDeleteProduct, {
  productId: "prod_123456789"
});
// result: { success: true }

​
Admin Create Store Category

Creates a store-level category under the store’s primary category. Store categories are used to organize products within a store.
​
storeId
Id<'stores'>
required
Store ID to create the category for
​
name
string
required
Category name in English
​
nameArabic
string
required
Category name in Arabic
​
isActive
boolean
Whether the category is active (default: true)
const categoryId = await convex.mutation(api.admins.storeOnboarding.adminCreateStoreCategory, {
  storeId: "s123456789",
  name: "Pizzas",
  nameArabic: "بيتزا",
  isActive: true
});

​
Admin Update Store Category

Updates a store-level category. Cannot update global (platform-level) categories.
​
categoryId
Id<'categories'>
required
Category ID to update
​
name
string
Updated category name
​
nameArabic
string
Updated Arabic category name
​
isActive
boolean
Updated active status
const categoryId = await convex.mutation(api.admins.storeOnboarding.adminUpdateStoreCategory, {
  categoryId: "cat_123456789",
  name: "Specialty Pizzas",
  nameArabic: "بيتزا مميزة"
});
This mutation only works on store-level categories (those with a storeId field). Attempting to update a global category will throw an error.

​
Admin Delete Store Category

Permanently deletes a store-level category. Cannot delete global categories.
​
categoryId
Id<'categories'>
required
Category ID to delete
const result = await convex.mutation(api.admins.storeOnboarding.adminDeleteStoreCategory, {
  categoryId: "cat_123456789"
});
// result: { success: true }
This mutation only works on store-level categories. Products assigned to this category will retain their category reference, but the category will no longer exist.

​
Admin Create Delivery Zone

Creates or updates a delivery zone for a store. If a zone already exists for the same store and city combination, it is updated (upsert behavior).
​
storeId
Id<'stores'>
required
Store ID to create the delivery zone for
​
city
Id<'cities'>
required
City ID for the delivery zone
​
areas
array
required
Array of area configurations, each containing:
  • area (Id<‘areas’>, required) — Area ID
  • deliveryFee (number) — Delivery fee for this area in AED
  • deliveryTime (number) — Estimated delivery time
  • deliveryTimeUnit (string) — Time unit: minutes, hours, or days
​
deliveryFee
number
Default delivery fee for the zone in AED
​
deliveryTime
number
Default delivery time for the zone
​
deliveryTimeUnit
string
Default delivery time unit: minutes, hours, or days
const result = await convex.mutation(api.admins.storeOnboarding.adminCreateDeliveryZone, {
  storeId: "s123456789",
  city: "city_dubai",
  areas: [
    { area: "area_downtown", deliveryFee: 10, deliveryTime: 30, deliveryTimeUnit: "minutes" },
    { area: "area_marina", deliveryFee: 15, deliveryTime: 45, deliveryTimeUnit: "minutes" }
  ],
  deliveryFee: 12,
  deliveryTime: 35,
  deliveryTimeUnit: "minutes"
});
// result: { id: "dz123456789", action: "created" }

{
  "id": "dz123456789",
  "action": "created"
}
If a delivery zone for the same store + city combination already exists, the zone is updated instead of creating a duplicate. The response action field indicates whether the zone was "created" or "updated".

​
Admin Delete Delivery Zone

Permanently deletes a delivery zone.
​
zoneId
Id<'storeDeliveryZones'>
required
Delivery zone ID to delete
const result = await convex.mutation(api.admins.storeOnboarding.adminDeleteDeliveryZone, {
  zoneId: "dz123456789"
});
// result: { success: true }