---
title: Configuration
description: Every Spree setting, the environment variable that sets it, and what it changes.
---

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.

```bash
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.

> **NOTE:** 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. |

## Related

- [Stores](../core-concepts/stores.md) — the settings a shop owns
- [Model preferences](model-preferences.md) — per-record settings
- [Services & Workflows](workflows.md) — changing behavior rather than settings