Quick Start Example - Payload

Let's walk through a practical example of setting up a simple job queue. We'll create a task that sends a welcome email when a user signs up.

You might wonder: "Why not just send the email directly in the afterChange hook?"

Non-blocking: If your email service takes 2-3 seconds to send, your API response would be delayed. With jobs, the API returns immediately.
Resilience: If the email service is temporarily down, the hook would fail and potentially block the user creation. Jobs can retry automatically.
Scalability: As your app grows, you can move job processing to dedicated servers, keeping your API fast.
Monitoring: All jobs are tracked in the database, so you can see if emails failed and why.

Now let's build this example step by step.

Step 1: Define a Task

First, create a task in your payload.config.ts:

import { buildConfig } from 'payload'

export default buildConfig({
  // ... other config
  jobs: {
    tasks: [
      {
        slug: 'sendWelcomeEmail',
        retries: 3,
        inputSchema: [
          {
            name: 'userEmail',
            type: 'email',
            required: true,
          },
          {
            name: 'userName',
            type: 'text',
            required: true,
          },
        ],
        handler: async ({ input, req }) => {
          // Send email using your email service
          await req.payload.sendEmail({
            to: input.userEmail,
            subject: 'Welcome!',
            text: `Hi ${input.userName}, welcome to our platform!`,
          })

          return {
            output: {
              emailSent: true,
            },
          }
        },
      },
    ],
  },
})

This defines a reusable task with a unique slug, an inputSchema that validates and types the input data, and a handler function containing the work to be performed. The retries option ensures the task will automatically retry up to 3 times if it fails. Learn more about Tasks.

Step 2: Queue the Job trigger

{
  slug: 'users',
  hooks: {
    afterChange: [
      async ({ req, doc, operation }) => {
        // Only send welcome email for new users
        if (operation === 'create') {
          await req.payload.jobs.queue({
            task: 'sendWelcomeEmail',
            input: {
              userEmail: doc.email,
              userName: doc.name,
            },
          })
        }
      },
    ],
  },
  // ... fields
}

This uses payload.jobs.queue() to create a job instance from the task definition. The job is added to the queue immediately but runs asynchronously, so the API response returns right away without waiting for the email to send. Jobs are stored in the database as documents in the payload-jobs collection.

Step 3: Run the Jobs

export default buildConfig({
  // ... other config
  jobs: {
    tasks: [
      /* ... */
    ],
    autoRun: [
      {
        cron: '*/5 * * * *', // Run every 5 minutes
      },
    ],
  },
})

The autoRun configuration automatically processes queued jobs on a schedule using cron syntax. In this example, Payload checks for pending jobs every 5 minutes and executes them. Alternatively, you can manually trigger job processing with payload.jobs.run() or use the API endpoint for serverless platforms.

That's it! Now when users sign up, a job is queued and will be processed within 5 minutes without blocking the API response.

Example 2: Recurring Scheduled Job

The previous example showed manual job queuing (jobs triggered by user actions). Now let's look at a job that runs automatically on a schedule without any user action.

We'll create a task that generates a daily analytics report every morning at 8 AM.

Why Use Scheduled Jobs?

Automated recurring tasks: No need to manually trigger them
Predictable timing: Reports, cleanups, syncs run at exact times
No manual intervention: Set it once and forget it

Step 1: Define a Task with Schedule

import { buildConfig } from 'payload'

export default buildConfig({
  // ... other config
  jobs: {
    tasks: [
      {
        slug: 'generateDailyReport',

        // This automatically queues a job every day at 8 AM
        schedule: [
          {
            cron: '0 8 * * *', // 8:00 AM daily
            queue: 'reports', // Put it in the 'reports' queue
          },
        ],

        inputSchema: [],

        outputSchema: [
          {
            name: 'reportId',
            type: 'text',
          },
        ],

        handler: async ({ req }) => {
          // Generate the report
          const yesterday = new Date()
          yesterday.setDate(yesterday.getDate() - 1)

          const analytics = await req.payload.find({
            collection: 'analytics',
            where: {
              createdAt: {
                greater_than_equal: yesterday.toISOString(),
              },
            },
          })

          // Save the report
          const report = await req.payload.create({
            collection: 'reports',
            data: {
              date: new Date().toISOString(),
              totalEvents: analytics.totalDocs,
              summary: `Generated report for ${yesterday.toDateString()}`,
            },
          })

          return {
            output: {
              reportId: report.id,
            },
          }
        },
      },
    ],
  },
})

The schedule property defines when this job should run (every day at 8 AM).

Step 2: Configure the Job Runner

To actually queue and execute scheduled jobs, you need to configure the autoRun property. This handles both queuing jobs based on their schedule and running them:

export default buildConfig({
  // ... other config
  jobs: {
    tasks: [
      /* task from step 1 */
    ],

    // This processes jobs from the 'reports' queue
    autoRun: [
      {
        cron: '* * * * *', // Check every minute
        queue: 'reports', // Process 'reports' queue
        limit: 10,
      },
    ],
  },
})

How It Works

Here's the complete flow:

At 8:00 AM: The schedule configuration automatically queues a new job in the 'reports' queue
Within 1 minute: The autoRun cron checks the 'reports' queue and finds the job
Execution: The job runs and generates the report
The next day: The process repeats automatically at 8:00 AM

<Banner type="error"> **Critical:** Both `schedule.queue` and `autoRun.queue` must use the same queue name ('reports' in this example). If they don't match, jobs will be queued but never executed. </Banner>

Complete Configuration

Here's the full config with both the task and runner:

import { buildConfig } from 'payload'

export default buildConfig({
  // ... other config
  jobs: {
    tasks: [
      {
        slug: 'generateDailyReport',
        schedule: [
          {
            cron: '0 8 * * *',
            queue: 'reports',
          },
        ],
        handler: async ({ req }) => {
          // Report generation logic
          const report = await generateReport()
          return { output: { reportId: report.id } }
        },
      },
    ],
    autoRun: [
      {
        cron: '* * * * *',
        queue: 'reports',
        limit: 10,
      },
    ],
  },
})

<Banner type="warning"> **For Serverless Platforms:** If deploying to Vercel or similar platforms, `autoRun` won't work. Use the [Vercel Cron approach](/docs/jobs-queue/queues#vercel-cron-example) instead. </Banner>

When to Use Each Approach

Approach	When to Use	Example
Manual Queuing	Jobs triggered by user actions or data changes	Welcome emails, payment processing, notifications
Scheduled Jobs	Jobs that run automatically at regular intervals	Daily reports, weekly cleanups, nightly syncs
Scheduled with Future	One-time job in the future	Publish post at 3pm tomorrow, trial expiry reminders

For scheduled jobs with waitUntil:

// Queue a one-time job for the future
await payload.jobs.queue({
  task: 'publishPost',
  input: { postId: '123' },
  waitUntil: new Date('2024-12-25T15:00:00Z'), // Runs once at this time
})

This is different from the schedule property, which repeats automatically.

See Job Schedules for more details on scheduling options and advanced patterns.