Documentation

Using Queues

Use queues for background execution, retry policy, delayed jobs, and concurrency control.

Try StackShiftRead the overview

Search Docs

Durable Jobs

Using Queues

Live

Use queues for background execution, retry policy, delayed jobs, and concurrency control.

Goal

Move work out of request handlers while keeping retries and visibility.

Current status

Live

This area is documented as current, user-reliable behavior.

Workflow

  1. 1Create or choose a queue name.
  2. 2Enqueue work with a job name and payload.
  3. 3Register a matching handler.
  4. 4Set retry and delay options per job when needed.

Enqueue jobs

Queue work

await stackshift.queue('emails').enqueue(
  'sendReceipt',
  { orderId: 'order_123', customerId: 'cus_123' },
  {
    idempotencyKey: 'receipt:order_123',
    maxAttempts: 5,
  }
)

Handlers

Handle queued work

stackshift.job<{ orderId: string; customerId: string }>('sendReceipt', async ({ payload, step }) => {
  const order = await step.run('load-order', () => loadOrder(payload.orderId))
  await step.run('send-receipt-email', () => sendReceiptEmail(order))

  return { sent: true }
})

Retries and delayed jobs

Retry later

ts
await stackshift.queue('billing').enqueue(
  'syncInvoice',
  { invoiceId: 'in_123' },
  {
    maxAttempts: 8,
    scheduledAt: '2026-05-06T09:00:00.000Z',
    idempotencyKey: 'invoice-sync:in_123',
  }
)

Expected result

Background work runs outside the request path and can be retried safely.