Configuration - Spree Commerce documentation

All business configuration is done in the Admin Dashboard. What is left here is a small set of settings describing the installation: limits, expiries, and where things are hosted. Every one of them is set with an environment variable, so changing one is a config change rather than a code change.

SPREE_MINIMUM_PASSWORD_LENGTH=10
SPREE_JWT_EXPIRATION=1800

Values are converted to the setting’s type, so SPREE_WEBHOOKS_ENABLED=false really is false. A value that cannot be converted — SPREE_JWT_EXPIRATION=abc — fails at boot rather than silently reverting to the default.

Booleans accept true/false, 1/0, yes/no and on/off, in any case.

Hosting

Variable	Default	What it does
`SPREE_DASHBOARD_URL`	—	Origin where the dashboard is hosted. Used for every link that sends someone into it — invitation emails, SSO redirects, and the first-run setup link printed by `db:seed`.
`SPREE_SELLER_PANEL_URL`	—	Origin where the marketplace seller panel is hosted, when it isn’t this app’s own `/sellers` mount. Unset uses `/sellers`; with no panel deployed, seller links open the dashboard.
`SPREE_STORE_SCOPE_GUARD`	`log`	Tripwire for queries that miss a store scope, in development and test only. `log` warns, `raise` fails, `off` disables. Never active in production.

Carts

Variable	Default	What it does
`SPREE_GUEST_CART_EXPIRY_DAYS`	`30`	How long an abandoned guest cart is kept before deletion.
`SPREE_CUSTOMER_CART_EXPIRY_DAYS`	`90`	How long a signed-in customer’s abandoned cart is kept.
`SPREE_EMPTY_CART_EXPIRY_HOURS`	`48`	How long a cart with no items is kept.

Products and pricing

Variable	Default	What it does
`SPREE_ALLOW_EMPTY_PRICE_AMOUNT`	`false`	Allows a price to be left blank instead of requiring an amount. Prices in a price list already allow blank.
`SPREE_ALWAYS_USE_TRANSLATIONS`	`false`	Always read product, category and collection names from the translation tables, even in the store’s own default language.

Payments

Variable	Default	What it does
`SPREE_CREDIT_TO_NEW_ALLOCATION`	`false`	Records refunded store credit as a new entry each time instead of topping the original credit back up.

Addresses

Variable	Default	What it does
`SPREE_GEOCODE_ADDRESSES`	`true`	Looks up latitude and longitude for saved addresses.

Uploads

Variable	Default	What it does
`SPREE_MAX_IMAGE_DOWNLOAD_SIZE`	`20971520`	Largest file accepted when downloading an image from an external URL, in bytes (20 MB).
`SPREE_IMAGES_SAVE_FROM_URL_JOB_ATTEMPTS`	`5`	How many times to retry fetching an external image before giving up.
`SPREE_MAX_VIDEO_UPLOAD_SIZE`	`524288000`	Largest product video accepted, in bytes (500 MB).
`SPREE_MAX_SELLER_DOCUMENT_UPLOAD_SIZE`	`20971520`	Largest document a seller may upload for a requirement, in bytes (20 MB). Small on purpose — these are certificates and registrations.

Promotions and gift cards

Variable	Default	What it does
`SPREE_COUPON_CODES_WEB_LIMIT`	`500`	How many coupon codes are created immediately when saving a promotion. Larger batches move to a background job so saving stays fast.
`SPREE_COUPON_CODES_TOTAL_LIMIT`	`5000`	Maximum coupon codes a single promotion may generate.
`SPREE_GIFT_CARD_BATCH_WEB_LIMIT`	`500`	How many gift card codes a batch creates immediately before switching to a background job.
`SPREE_GIFT_CARD_BATCH_LIMIT`	`50000`	Maximum gift card codes in a single batch.

Accounts and passwords

Variable	Default	What it does
`SPREE_MINIMUM_PASSWORD_LENGTH`	`8`	Shortest password a customer or staff member may set.
`SPREE_MAXIMUM_PASSWORD_LENGTH`	`ActiveModel::SecurePassword::MAXPASSWORDLENGTHALLOWED`	Longest password allowed.
`SPREE_MAX_FAILED_LOGIN_ATTEMPTS`	`5`	Failed sign-ins before an account is temporarily locked.
`SPREE_LOCKOUT_DURATION`	`1800`	How long an account stays locked, in seconds.
`SPREE_CUSTOMER_PASSWORD_RESET_EXPIRES_IN`	`15`	How long a customer’s password reset link stays valid, in minutes.
`SPREE_ADMIN_PASSWORD_RESET_EXPIRES_IN`	`15`	How long a staff password reset link stays valid, in minutes.

Imports and events

Variable	Default	What it does
`SPREE_LARGE_IMPORT_THRESHOLD`	`500`	Row count above which a CSV import switches to bulk processing — faster, with less live progress detail.
`SPREE_EVENTS_LOG_ENABLED`	`true`	Writes every Spree event to the Rails log.
`SPREE_DISABLE_MIGRATION_CHECK`	`false`	Silences the boot warning about pending engine migrations.

API authentication

Variable	Default	What it does
`SPREE_JWT_EXPIRATION`	`3600`	How long a customer or store access token stays valid, in seconds.
`SPREE_ADMIN_JWT_EXPIRATION`	`300`	How long a staff access token stays valid. Deliberately short — staff tokens carry far more privilege.
`SPREE_REFRESH_TOKEN_EXPIRY`	`2592000`	How long a refresh token stays valid, in seconds (30 days).
`SPREE_JWT_SECRET_KEY`	—	Signing key for tokens. Falls back to `Rails.application.credentials.jwt_secret_key`, then the Rails secret key base.

API rate limits

Variable	Default	What it does
`SPREE_RATE_LIMIT_WINDOW`	`60`	Length of the rate-limit window, in seconds.
`SPREE_RATE_LIMIT_PER_KEY`	`300`	Requests per window for each publishable key + client IP pair, and for keyless traffic per IP. Across the whole API, not per endpoint.
`SPREE_RATE_LIMIT_PER_SECRET_KEY`	`600`	Requests per secret API key per window, across the whole API.
`SPREE_RATE_LIMIT_LOGIN`	`5`	Sign-in attempts allowed per IP per window.
`SPREE_RATE_LIMIT_REGISTER`	`3`	Registration attempts per IP.
`SPREE_RATE_LIMIT_REFRESH`	`10`	Token refresh attempts per IP.
`SPREE_RATE_LIMIT_PASSWORD_RESET`	`3`	Password reset requests per IP.
`SPREE_MAX_REQUEST_BODY_SIZE`	`102400`	Largest accepted request body, in bytes (100 KB).

Webhooks

Variable	Default	What it does
`SPREE_WEBHOOKS_ENABLED`	`true`	Whether webhooks fire at all.
`SPREE_WEBHOOKS_VERIFY_SSL`	`true`	Verifies SSL certificates on webhook endpoints. Off in development.

Stores — the settings a shop owns
Model preferences — per-record settings
Services & Workflows — changing behavior rather than settings

​Hosting

​Carts

​Products and pricing

​Payments

​Addresses

​Uploads

​Promotions and gift cards

​Accounts and passwords

​Imports and events

​API authentication

​API rate limits

​Webhooks

​Related

Hosting

Carts

Products and pricing

Payments

Addresses

Uploads

Promotions and gift cards

Accounts and passwords

Imports and events

API authentication

API rate limits

Webhooks

Related