Background Jobs - Spree Commerce documentation

Everything that doesn’t happen during a request runs as a background job: sending emails, processing images, delivering webhooks, importing and exporting catalogs, releasing expired stock reservations. Spree uses Active Job (Rails’ standard job interface), so the queue backend is swappable — but the default needs nothing beyond your database.

Solid Queue — the default

Production uses Solid Queue — the built-in background job processor: jobs are stored in your database alongside everything else. There is nothing extra to provision, and by default the job supervisor runs inside the web container — one container is the whole application (combined mode). When job volume grows, switch to split mode: run a dedicated worker from the same image with bin/jobs, and set SOLID_QUEUE_IN_PUMA=false on the web service. Multiple web instances and multiple workers are safe by default — they coordinate through the database.

Variable	Default	Description
`SOLID_QUEUE_IN_PUMA`	`true`	Run jobs inside the web container; set `false` when a dedicated worker runs
`JOB_THREADS`	`3`	Worker thread count — raise it on a dedicated worker
`JOB_CONCURRENCY`	`1`	Worker process count — the scaling knob for dedicated workers

Job Dashboard

Every deployment ships Mission Control — a web UI for background jobs — at /jobs: inspect, retry, and discard jobs from the browser. It’s guarded by HTTP Basic auth: set MISSION_CONTROL_USER and MISSION_CONTROL_PASSWORD in production (without them the dashboard stays locked).

Recurring Jobs

Scheduled work is defined in config/recurring.yml, Solid Queue’s built-in cron. A new project already schedules everything Spree needs:

Schedule	Job	What it does
Every minute	`Spree::StockReservations::ExpireJob`	Releases checkout stock reservations whose hold expired
Every 5 minutes	`Spree::Orders::FinalizeStaleDraftsJob`	Finishes orders whose payment succeeded but whose completion never committed; never refunds
Hourly	`Spree::Carts::ReapExpiredJob`	Deletes abandoned carts past their expiry; carts with a live payment are kept
Hourly	`Spree::Collections::RegenerateTimeBasedJob`	Refreshes automatic collections with time-based rules, such as “available on”
Daily	`spree:price_history:prune` task	Deletes price history older than each store’s retention period (EU Omnibus)
Daily	`Spree::SellerPayouts::SweepDueJob`	Settles marketplace sellers who are due a payout (see below)
Hourly	`Spree::SellerTransfers::ExecutePendingDueJob`	Retries seller earnings a payout provider refused

The marketplace jobs do nothing on a store with no sellers, so keep them enabled. If your project predates any of these, copy the missing entries from the starter’s config/recurring.yml. Add your own:

config/recurring.yml

production:
  nightly_report:
    class: MyReportJob
    schedule: at 5am every day

Marketplace payouts

A marketplace settles its sellers on a recurring job, which a new project already schedules:

config/recurring.yml

production:
  sweep_due_seller_payouts:
    class: Spree::SellerPayouts::SweepDueJob
    schedule: at 3am every day

Run it daily whatever intervals your sellers are on. The job only fans out; whether a given seller is due — and when they were last settled — is decided per seller, because a cron expression cannot say “weekly, counted from that seller’s own last payout”. A seller whose interval is manual is skipped here by design and is settled by hand from the operator dashboard.

Queues

config/queue.yml lists queues in polling order: checkout-critical and operator-facing work first, bulk catalog processing second, housekeeping last. A trailing "*" catches any queue added later. Large CSV imports are additionally capped so they can’t occupy the whole worker pool — see SPREE_IMPORT_JOB_CONCURRENCY.

Swapping to Sidekiq

For very high job volume, Spree works with Sidekiq on Redis or Valkey — like any Active Job backend. This is a bigger step than the cache swap; here is the full setup. Add the gems and switch the adapter:

# Gemfile
gem "sidekiq"
gem "sidekiq-cron"      # recurring jobs (replaces config/recurring.yml)
gem "sentry-sidekiq"    # only if you use Sentry

# config/application.rb
config.active_job.queue_adapter = :sidekiq

Configure the queues with weights — Sidekiq’s equivalent of Solid Queue’s polling order (checkout-critical work first, bulk catalog processing second, housekeeping last):

config/sidekiq.yml

:concurrency: <%= Integer(ENV.fetch('SIDEKIQ_CONCURRENCY', '10')) %>
:queues:
  - [default, 5]
  - [spree_imports, 5]
  - [spree_payment_webhooks, 5]
  - [mailers, 5]
  - [spree_events, 3]
  - [spree_exports, 3]
  - [spree_images, 3]
  - [spree_stock_reservations, 5]
  - [spree_products, 3]
  - [spree_variants, 3]
  - [spree_categories, 3]
  - [spree_collections, 3]
  - [spree_stock_location_stock_levels, 3]
  - [spree_coupon_codes, 3]
  - [spree_addresses, 3]
  - [spree_gift_cards, 3]
  - [spree_webhooks, 3]
  - [spree_api_keys, 3]
  - [spree_search, 3]
  - [spree_tax_identifiers, 3]
  - [spree_payouts, 3]
  - [spree_data_requests, 1]
  - [active_storage_transform, 3]
  - [active_storage_analysis, 1]
  - [active_storage_purge, 1]

Unlike Solid Queue, Sidekiq has no catch-all queue: a job on a queue missing from this list never runs. Every queue name you assign with Spree.queues in config/initializers/spree.rb must appear here. Any Spree.queues entry you don’t assign uses default. Move the config/recurring.yml schedules to sidekiq-cron (it auto-loads config/schedule.yml):

config/schedule.yml

expire_stock_reservations:
  cron: "* * * * *"
  class: Spree::StockReservations::ExpireJob
finalize_stale_draft_orders:
  cron: "*/5 * * * *"
  class: Spree::Orders::FinalizeStaleDraftsJob
reap_expired_carts:
  cron: "7 * * * *"
  class: Spree::Carts::ReapExpiredJob
regenerate_time_based_collections:
  cron: "17 * * * *"
  class: Spree::Collections::RegenerateTimeBasedJob
prune_price_history:
  cron: "0 4 * * *"
  class: PrunePriceHistoryJob
sweep_due_seller_payouts:
  cron: "0 3 * * *"
  class: Spree::SellerPayouts::SweepDueJob
execute_pending_seller_transfers:
  cron: "27 * * * *"
  class: Spree::SellerTransfers::ExecutePendingDueJob

sidekiq-cron schedules jobs, not commands, so price history pruning needs a small job that runs the task:

app/jobs/prune_price_history_job.rb

require 'rake'

class PrunePriceHistoryJob < ApplicationJob
  def perform
    Rails.application.load_tasks unless Rake::Task.task_defined?('spree:price_history:prune')
    Rake::Task['spree:price_history:prune'].tap(&:reenable).invoke
  end
end

The /jobs dashboard is Solid Queue-specific — mount Sidekiq’s Web UI instead:

# config/routes.rb
require "sidekiq/web"

Sidekiq::Web.use Rack::Auth::Basic do |user, password|
  ActiveSupport::SecurityUtils.secure_compare(user, ENV["SIDEKIQ_USER"].to_s) &
    ActiveSupport::SecurityUtils.secure_compare(password, ENV["SIDEKIQ_PASSWORD"].to_s)
end
mount Sidekiq::Web => "/sidekiq"

Finally: point Sidekiq at your Redis/Valkey via REDIS_URL, run bundle exec sidekiq as a dedicated worker service (set RAILS_MAX_THREADS to at least SIDEKIQ_CONCURRENCY there so the database pool covers every worker thread), and remove the SOLID_QUEUE_IN_PUMA setting — with Sidekiq, web and worker are always separate processes. Reach for this when a dedicated Solid Queue worker with raised JOB_THREADS/JOB_CONCURRENCY no longer keeps up — for most stores, that point never arrives.

​Solid Queue — the default

​Job Dashboard

​Recurring Jobs

​Marketplace payouts

​Queues

​Swapping to Sidekiq