TWIGZ Backend API Documentation

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.

string

required

Store name

string

Store name in Arabic

string

Store description

Id<'categories'>

required

Primary category ID for the store

string

Owner’s Clerk user ID. Defaults to "admin_managed" if not provided.

string

required

Store owner’s full name

string

required

Store owner’s phone number

string

Store contact email

Id<'_storage'>

Storage ID for the store logo image

Id<'_storage'>

Storage ID for the store cover/banner image

Id<'_storage'>

Storage ID for the trade license document

boolean

If true, store is created with approved status, isActive: true, and a wallet is initialized automatically

object

Store settings:

deliveryEnabled — Whether delivery is enabled
pickupEnabled — Whether pickup is enabled
allowsReturns — Whether returns are accepted
returnWindowDays — Return window in days

object

Bank account details:

IBAN — Bank IBAN number
bankName — Bank name
bankId — Bank ID reference
accountHolderName — Account holder name

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.

Id<'stores'>

required

Store ID to update

string

Updated store name

string

Updated store name in Arabic

string

Updated description

Id<'categories'>

Updated primary category (triggers counter updates)

string

Updated owner user ID

string

Updated owner name

string

Updated phone number

string

Updated email

Id<'_storage'>

Updated logo storage ID

Id<'_storage'>

Updated cover image storage ID

Id<'_storage'>

Updated trade license storage ID

object

Updated store settings (same structure as create)

object

Updated bank account details (same structure as create)

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.

Id<'stores'>

required

Store ID to add the product to

string

required

Product name

string

Product description

Id<'categories'>

required

Product category ID (must be a child of the store’s primary category)

number

required

Product price in AED

number

Product cost (for profit tracking)

number

Available stock quantity

number

Low stock alert threshold

number

Preparation time value

string

Preparation time unit: minutes, hours, or days

boolean

required

Whether the product is active and visible

Id<'_storage'>

required

Storage ID for the primary product image

Id<'_storage'>[]

Additional product image storage IDs

boolean

Whether the product can be returned

boolean

Whether delivery is available for this product

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.

Id<'products'>

required

Product ID to update

string

Updated product name

string

Updated description

Id<'categories'>

Updated category

number

Updated price

number

Updated cost

number

Updated stock quantity

number

Updated stock alert threshold

number

Updated preparation time

string

Updated preparation time unit: minutes, hours, or days

boolean

Updated active status

Id<'_storage'>

Updated primary image storage ID

Id<'_storage'>[]

Updated additional images

boolean

Updated returnable flag

boolean

Updated delivery flag

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.

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.

Id<'stores'>

required

Store ID to create the category for

string

required

Category name in English

string

required

Category name in Arabic

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.

Id<'categories'>

required

Category ID to update

string

Updated category name

string

Updated Arabic category name

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.

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).

Id<'stores'>

required

Store ID to create the delivery zone for

Id<'cities'>

required

City ID for the delivery zone

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

number

Default delivery fee for the zone in AED

number

Default delivery time for the zone

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.

Id<'storeDeliveryZones'>

required

Delivery zone ID to delete

const result = await convex.mutation(api.admins.storeOnboarding.adminDeleteDeliveryZone, {
  zoneId: "dz123456789"
});
// result: { success: true }

Shared Functions

Store Management

Customer Experience

Admin & Platform

HTTP Endpoints

Scheduled Tasks

Database

Development

Store Onboarding

Overview

Admin Create Store

Admin Update Store

Admin Create Product

Admin Update Product

Admin Delete Product

Admin Create Store Category

Admin Update Store Category

Admin Delete Store Category

Admin Create Delivery Zone

Admin Delete Delivery Zone

​Overview

​Admin Create Store

​Admin Update Store

​Admin Create Product

​Admin Update Product

​Admin Delete Product

​Admin Create Store Category

​Admin Update Store Category

​Admin Delete Store Category

​Admin Create Delivery Zone

​Admin Delete Delivery Zone

Overview

Admin Create Store

Admin Update Store

Admin Create Product

Admin Update Product

Admin Delete Product

Admin Create Store Category

Admin Update Store Category

Admin Delete Store Category

Admin Create Delivery Zone

Admin Delete Delivery Zone