TWIGZ Backend API Documentation

Overview

Notification Settings API allows administrators to configure their notification delivery preferences, including per-category email and web notification toggles. Settings are stored per admin and control which notifications trigger email delivery via Resend. All functions require authentication. Location: convex/admins/notificationSettings.ts

Get Notification Settings

Returns the current admin’s notification settings, or null if no settings have been initialized yet. No parameters required.

const settings = await convex.query(api.admins.notificationSettings.getNotificationSettings, {});

{
  "_id": "ns123456789",
  "_creationTime": 1700000000000,
  "adminId": "user_abc123",
  "emailEnabled": true,
  "webEnabled": true,
  "emailPreferences": {
    "storeApprovals": true,
    "payoutRequests": true,
    "reviewFlags": true,
    "orderIssues": true
  },
  "webPreferences": {
    "storeApprovals": true,
    "payoutRequests": true,
    "reviewFlags": false,
    "orderIssues": true
  },
  "emailAddress": "admin@twigz.app",
  "updatedAt": 1700000000000
}

Returns null if settings have not been initialized. Call initializeDefaultSettings to create default settings for a new admin.

Update Notification Settings

Updates notification settings for the current admin. All fields are optional and only provided fields are updated. If no settings record exists, one is created with sensible defaults for any omitted fields.

emailEnabled

boolean

Master toggle for email notifications

webEnabled

boolean

Master toggle for web/in-app notifications

emailPreferences

object

Per-category email notification toggles

Show properties

storeApprovals

boolean

Receive emails for store approval requests

payoutRequests

boolean

Receive emails for payout requests

reviewFlags

boolean

Receive emails for flagged reviews

orderIssues

boolean

Receive emails for order issues

webPreferences

object

Per-category web notification toggles

Show properties

storeApprovals

boolean

Show web notifications for store approval requests

payoutRequests

boolean

Show web notifications for payout requests

reviewFlags

boolean

Show web notifications for flagged reviews

orderIssues

boolean

Show web notifications for order issues

emailAddress

string

Email address for notification delivery

const settingsId = await convex.mutation(api.admins.notificationSettings.updateNotificationSettings, {
  emailEnabled: true,
  emailPreferences: {
    storeApprovals: true,
    payoutRequests: true,
    reviewFlags: false,
    orderIssues: true
  },
  emailAddress: "admin@twigz.app"
});

"ns123456789"

Initialize Default Settings

Creates default notification settings for a new admin. All notification categories are enabled by default for both email and web channels. If settings already exist for the admin, returns the existing settings ID without modification.

emailAddress

string

required

Email address to use for notification delivery

const settingsId = await convex.mutation(api.admins.notificationSettings.initializeDefaultSettings, {
  emailAddress: "admin@twigz.app"
});

"ns123456789"

This is idempotent — calling it when settings already exist returns the existing record ID. Call this when an admin first logs in to ensure they have notification settings configured.

Send Test Notification

Sends a test notification to verify that the email delivery pipeline is working. Creates an in-app notification (visible in the notification bell) and schedules a test email to the admin’s configured email address. No parameters required.

const result = await convex.mutation(api.admins.notificationSettings.sendTestNotification, {});

{
  "success": true,
  "message": "Test notification created! Check the notification bell and your email at admin@twigz.app (including spam folder)."
}

Possible failure responses:

{
  "success": false,
  "message": "No notification settings found. Please save your settings first."
}

{
  "success": false,
  "message": "Email notifications are disabled. Please enable them to receive test emails."
}

{
  "success": false,
  "message": "No email address configured. Please add an email address to your settings."
}

The test notification is created with type order_issue and priority low. Email delivery is handled asynchronously via Resend.

Shared Functions

Store Management

Customer Experience

Admin & Platform

HTTP Endpoints

Scheduled Tasks

Database

Development

Notification Settings

Overview

Get Notification Settings

Update Notification Settings

Initialize Default Settings

Send Test Notification

​Overview

​Get Notification Settings

​Update Notification Settings

​Initialize Default Settings

​Send Test Notification

Overview

Get Notification Settings

Update Notification Settings

Initialize Default Settings

Send Test Notification