---
title: "Schedule a push notification"
method: POST
path: "/notifications/scheduled"
tags: ["scheduled-notifications"]
---

# Schedule a push notification

`POST /notifications/scheduled`

Schedule a push notification to be sent at a specific date and time. 
    The notification will be automatically sent by the system when the scheduled time arrives.
    Requires admin approval before being sent.
    Supports multiple target types: single user, multiple users, all users, device tokens, topics, or conditions.

## Request body

- ScheduleNotificationDto
  - `title` string, required — Notification title
  - `body` string, required — Notification body
  - `scheduledTime` string, required — ISO 8601 formatted date-time when notification should be sent
  - `targetType` 'user' | 'users' | 'all_users' | 'tokens' | 'topic' | 'condition', required — Target type for the notification
  - `targetValue` object — Target value (userId, userIds array, device tokens, topic name, or condition). Required based on targetType.
  - `data` object — Additional custom data payload
  - `imageUrl` string — Image URL for notification
  - `clickAction` string — Click action or deep link
  - `timezone` string — Timezone for scheduling
  - `createdBy` string — User or admin who created this scheduled notification
  - `isRecurring` boolean — Whether this is a recurring notification
  - `recurrenceRule` string — Cron expression for recurring notifications (e.g., "0 9 * * 1" for every Monday at 9 AM)

## Response `201`

Notification scheduled successfully (pending admin approval)

- ScheduledNotificationResponseDto
  - `notification_id` number, required — Notification ID
  - `title` string, required — Notification title
  - `body` string, required — Notification body
  - `scheduled_time` string, date-time, required — Scheduled time
  - `timezone` string, required — Timezone
  - `target_type` 'user' | 'users' | 'all_users' | 'tokens' | 'topic' | 'condition', required — Target type
  - `target_value` object — Target value
  - `status` 'pending_approval' | 'pending' | 'processing' | 'sent' | 'failed' | 'cancelled' | 'expired' | 'rejected', required — Current status
  - `sent_at` string, date-time — Sent timestamp
  - `success_count` number, required — Number of successful sends
  - `failure_count` number, required — Number of failed sends
  - `error_message` string — Error message if failed
  - `created_at` string, date-time, required — Created timestamp
  - `updated_at` string, date-time, required — Updated timestamp

## Other responses

- `400` — Bad request - Invalid data (e.g., scheduled time in the past, invalid target configuration)
- `401` — Unauthorized - Invalid or missing JWT token

---

[API](https://skmtc.dev/tonewow/apis/tonewow-database-api.md) · [All operations](https://skmtc.dev/tonewow/apis/tonewow-database-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tonewow/tonewow-database-api/revisions/f36472974ad4/schema)