Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Background Jobs
description: Spree's background jobs live in your database by default (Solid Queue) — nothing extra to run, with a Sidekiq/Redis swap for very high volume.
---
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](https://github.com/rails/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](/developer/deployment/quickstart#web-and-worker)).
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](https://github.com/rails/mission_control-jobs) — 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`](https://github.com/spree/spree-starter/blob/main/config/recurring.yml).
Add your own:
```yaml 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:
```yaml 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`](/developer/deployment/environment_variables).
## Swapping to Sidekiq
For very high job volume, Spree works with [Sidekiq](https://sidekiq.org/) on Redis or Valkey — like any Active Job backend. This is a bigger step than the [cache swap](/developer/deployment/caching); here is the full setup.
Add the gems and switch the adapter:
```ruby
# 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):
```yaml 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`):
```yaml 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:
```ruby 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](https://github.com/sidekiq/sidekiq/wiki/Monitoring) instead:
```ruby
# 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.