Job Schedules

Payload's schedule property lets you enqueue Jobs regularly according to a cron schedule - daily, weekly, hourly, or any custom interval. This is ideal for tasks or workflows that must repeat automatically and without manual intervention.

Scheduling Jobs differs significantly from running them:

Queueing: Scheduling only creates (enqueues) the Job according to your cron expression. It does not immediately execute any business logic.
Running: Execution happens separately through your Jobs runner - such as autorun, or manual invocation using payload.jobs.run() or the payload-jobs/run endpoint.

Use the schedule property specifically when you have recurring tasks or workflows. To enqueue a single Job to run once in the future, use the waitUntil property instead.

When to use Schedules

Here's a quick guide to help you choose the right approach:

Approach	Use Case	Example
Schedule	Recurring tasks that run automatically on a schedule	Daily reports, weekly emails, hourly syncs
waitUntil	One-time job in the future	Publish a post at 3pm tomorrow, send trial expiry email in 7 days
Collection Hook	Job triggered by document changes	Send email when post is published, generate PDF when order is created
Manual Queue	Job triggered by user action or API call	User clicks "Generate Report" button

Example comparison:

1// Bad practice - Using schedule for one-time future job
2schedule: [{ cron: '0 15 * * *', queue: 'default' }] // Runs every day at 3pm
3
4// Best practice - Use waitUntil for one-time future job
5await payload.jobs.queue({
6  task: 'publishPost',
7  input: { postId: '123' },
8  waitUntil: new Date('2024-12-25T15:00:00Z'), // Runs once at this specific time
9})
10
11// Best practice - Use schedule for recurring jobs
12schedule: [{ cron: '0 0 * * *', queue: 'nightly' }] // Runs every day at midnight

Handling schedules

Something needs to actually trigger the scheduling of jobs (execute the scheduling lifecycle seen below). By default, the jobs.autorun configuration, as well as the /api/payload-jobs/run will also handle scheduling for the queue specified in the autorun configuration.

You can disable this behavior by setting disableScheduling: true in your autorun configuration, or by passing disableScheduling=true to the /api/payload-jobs/run endpoint. This is useful if you want to handle scheduling manually, for example, by using a cron job or a serverless function that calls the /api/payload-jobs/handle-schedules endpoint or the payload.jobs.handleSchedules() local API method.

Bin Scripts

Payload provides a set of bin scripts that can be used to handle schedules. If you're already using the jobs:run bin script, you can set it to also handle schedules by passing the --handle-schedules flag:

1pnpm payload jobs:run --cron "*/5 * * * *" --queue myQueue --handle-schedules # This will both schedule jobs according to the configuration and run them

If you only want to handle schedules, you can use the dedicated jobs:handle-schedules bin script:

1pnpm payload jobs:handle-schedules --cron "*/5 * * * *" --queue myQueue # or --all-queues

Defining schedules on Tasks or Workflows

Schedules are defined using the schedule property:

1export type ScheduleConfig = {
cron: string // required, supports seconds precision
queue: string // required, the queue to push Jobs onto
hooks?: {
  // Optional hooks to customize scheduling behavior
  beforeSchedule?: BeforeScheduleFn
  afterSchedule?: AfterScheduleFn
}
9}

Example schedule

The following example demonstrates scheduling a Job to enqueue every day at midnight:

1import type { TaskConfig } from 'payload'
2
3export const SendDigestEmail: TaskConfig<'SendDigestEmail'> = {
slug: 'SendDigestEmail',
schedule: [
  {
    cron: '0 0 * * *', // Every day at midnight
    queue: 'nightly',
  },
],
handler: async () => {
  await sendDigestToAllUsers()
},
14}

This configuration only queues the Job - it does not execute it immediately. To actually run the queued Job, you configure autorun in your Payload config (note that autorun should not be used on serverless platforms):

1export default buildConfig({
jobs: {
  autoRun: [
    {
      cron: '* * * * *', // Runs every minute
      queue: 'nightly',
    },
  ],
  tasks: [SendDigestEmail],
},
11})

That way, Payload's scheduler will automatically enqueue the job into the nightly queue every day at midnight. The autorun configuration will check the nightly queue every minute and execute any Jobs that are due to run.

Scheduling lifecycle

Here's how the scheduling process operates in detail:

Cron evaluation: Payload (or your external trigger in manual mode) identifies which schedules are due to run. To do that, it will read the payload-jobs-stats global which contains information about the last time each scheduled task or workflow was run.
BeforeSchedule hook:

The default beforeSchedule hook checks how many active or runnable jobs of the same type that have been queued by the scheduling system currently exist. If such a job exists, it will skip scheduling a new one.
You can provide your own beforeSchedule hook to customize this behavior. For example, you might want to allow multiple overlapping Jobs or dynamically set the Job input data.

Enqueue Job: Payload queues up a new job. This job will have waitUntil set to the next scheduled time based on the cron expression.
AfterSchedule hook:

The default afterSchedule hook updates the payload-jobs-stats global metadata with the last scheduled time for the Job.
You can provide your own afterSchedule hook to it for custom logging, metrics, or other post-scheduling actions.

Customizing concurrency and input

You may want more control over concurrency or dynamically set Job inputs at scheduling time. For instance, allowing multiple overlapping Jobs to be scheduled, even if a previously scheduled job has not completed yet, or preparing dynamic data to pass to your Job handler:

1import { countRunnableOrActiveJobsForQueue } from 'payload'
2
3schedule: [
{
  cron: '* * * * *', // every minute
  queue: 'reports',
  hooks: {
    beforeSchedule: async ({ queueable, req }) => {
      const runnableOrActiveJobsForQueue =
        await countRunnableOrActiveJobsForQueue({
          queue: queueable.scheduleConfig.queue,
          req,
          taskSlug: queueable.taskConfig?.slug,
          workflowSlug: queueable.workflowConfig?.slug,
          onlyScheduled: true,
        })
17
      // Allow up to 3 simultaneous scheduled jobs and set dynamic input
      return {
        shouldSchedule: runnableOrActiveJobsForQueue < 3,
        input: { text: 'Hi there' },
      }
    },
  },
},
26]

This allows fine-grained control over how many Jobs can run simultaneously and provides dynamically computed input values each time a Job is scheduled.

Scheduling in serverless environments

On serverless platforms, scheduling must be triggered externally since Payload does not automatically run cron schedules in ephemeral environments. You have two main ways to trigger scheduling manually:

Invoke via Payload's API: payload.jobs.handleSchedules()
Use the REST API endpoint: /api/payload-jobs/handle-schedules
Use the run endpoint, which also handles scheduling by default: GET /api/payload-jobs/run

For example, on Vercel, you can set up a Vercel Cron to regularly trigger scheduling:

Vercel Cron Job: Configure Vercel Cron to periodically call GET /api/payload-jobs/handle-schedules. If you would like to auto-run your scheduled jobs as well, you can use the GET /api/payload-jobs/run endpoint.

Once Jobs are queued, their execution depends entirely on your configured runner setup (e.g., autorun, or manual invocation).

Common Schedule Patterns

Here are typical cron expressions for common scheduling needs:

1// Every minute
2schedule: [{ cron: '* * * * *', queue: 'frequent' }]
3
4// Every 5 minutes
5schedule: [{ cron: '*/5 * * * *', queue: 'default' }]
6
7// Every hour at minute 0
8schedule: [{ cron: '0 * * * *', queue: 'hourly' }]
9
10// Every day at midnight (00:00)
11schedule: [{ cron: '0 0 * * *', queue: 'nightly' }]
12
13// Every day at 2:30 AM
14schedule: [{ cron: '30 2 * * *', queue: 'nightly' }]
15
16// Every Monday at 9:00 AM
17schedule: [{ cron: '0 9 * * 1', queue: 'weekly' }]
18
19// First day of every month at midnight
20schedule: [{ cron: '0 0 1 * *', queue: 'monthly' }]
21
22// Every weekday (Mon-Fri) at 8:00 AM
23schedule: [{ cron: '0 8 * * 1-5', queue: 'weekdays' }]
24
25// Every 30 seconds (with seconds precision)
26schedule: [{ cron: '*/30 * * * * *', queue: 'frequent' }]

Cron format reference:

1* * * * * *
2│ │ │ │ │ │
3│ │ │ │ │ └─ Day of week (0-7, 0 and 7 = Sunday)
4│ │ │ │ └─── Month (1-12)
5│ │ │ └───── Day of month (1-31)
6│ │ └─────── Hour (0-23)
7│ └───────── Minute (0-59)
8└─────────── Second (0-59, optional)

Real-World Examples

Daily digest email:

1export const DailyDigestTask: TaskConfig<'DailyDigest'> = {
slug: 'DailyDigest',
schedule: [
  {
    cron: '0 7 * * *', // Every day at 7:00 AM
    queue: 'emails',
  },
],
handler: async ({ req }) => {
  const users = await req.payload.find({
    collection: 'users',
    where: { digestEnabled: { equals: true } },
  })
14
  for (const user of users.docs) {
    await sendDigestEmail(user.email)
  }
18
  return { output: { emailsSent: users.docs.length } }
},
21}

Weekly report generation:

1export const WeeklyReportTask: TaskConfig<'WeeklyReport'> = {
slug: 'WeeklyReport',
schedule: [
  {
    cron: '0 9 * * 1', // Every Monday at 9:00 AM
    queue: 'reports',
  },
],
handler: async ({ req }) => {
  const report = await generateWeeklyReport()
  await req.payload.create({
    collection: 'reports',
    data: report,
  })
15
  return { output: { reportId: report.id } }
},
18}

Hourly data sync:

1export const SyncDataTask: TaskConfig<'SyncData'> = {
slug: 'SyncData',
schedule: [
  {
    cron: '0 * * * *', // Every hour
    queue: 'sync',
  },
],
handler: async ({ req }) => {
  const data = await fetchFromExternalAPI()
  await req.payload.create({
    collection: 'synced-data',
    data,
  })
15
  return { output: { itemsSynced: data.length } }
},
18}

Troubleshooting Schedules

Here are a few things to check when scheduled jobs are not being queued:

Is schedule handling enabled?

1// Make sure autoRun doesn't disable scheduling
2jobs: {
autoRun: [
  {
    cron: '*/5 * * * *',
    queue: 'default',
    disableScheduling: false, // Should be false or omitted
  },
],
10}

Is the cron expression valid?

1// Invalid cron - 6 fields (with seconds) but missing day of week
2schedule: [{ cron: '0 0 * * *', queue: 'default' }] // Missing 6th field
3
4// Valid cron - 5 fields (standard format)
5schedule: [{ cron: '0 0 * * *', queue: 'default' }]
6
7// Valid cron - 6 fields (with seconds)
8schedule: [{ cron: '0 0 0 * * *', queue: 'default' }]

Test your cron expressions at crontab.guru (for 5-field format).

Check the payload-jobs-stats global

1const stats = await payload.findGlobal({
2  slug: 'payload-jobs-stats',
3})
4
5console.log(stats.lastScheduled) // Check when each task was last scheduled

Scheduled Jobs queued but not running

This means scheduling is working, but execution isn't. See the Queues troubleshooting section.

Jobs running at wrong times

Issue: Job scheduled for midnight but runs immediately

This happens when waitUntil isn't set properly. Check your schedule config:

1// The schedule property only queues the job
2// The autoRun picks it up and runs it
3schedule: [{ cron: '0 0 * * *', queue: 'nightly' }]
4
5// Make sure autoRun checks the queue frequently enough
6autoRun: [
7  {
8    cron: '* * * * *', // Check every minute
9    queue: 'nightly',
10  },
11]

Multiple instances of the same scheduled job

By default, Payload prevents duplicate scheduled jobs. If you're seeing duplicates:

Are you running multiple servers without coordination?

If multiple servers are handling schedules, they might each queue jobs. Solution: Only enable schedule handling on one server:

1// Server 1 (handles schedules)
2jobs: {
3  shouldAutoRun: () => process.env.HANDLE_SCHEDULES === 'true',
4  autoRun: [/* ... */],
5}
6
7// Server 2 (just processes jobs, no scheduling)
8jobs: {
9  shouldAutoRun: () => process.env.HANDLE_SCHEDULES !== 'true',
10  autoRun: [{ disableScheduling: true }],
11}

Custom beforeSchedule hook

If you have a custom beforeSchedule hook, make sure it properly checks for existing jobs:

1import { countRunnableOrActiveJobsForQueue } from 'payload'
2
3hooks: {
4  beforeSchedule: async ({ queueable, req }) => {
5    const count = await countRunnableOrActiveJobsForQueue({
6      queue: queueable.scheduleConfig.queue,
7      req,
8      taskSlug: queueable.taskConfig?.slug,
9      onlyScheduled: true,
10    })
11
12    return {
13      shouldSchedule: count === 0, // Only schedule if no jobs exist
14    }
15  },
16}

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.