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: Validations
section: customization
---
## Overview
Adding a rule — and occasionally relaxing one Spree ships — is one of the most
common reasons to reach into core models. There are three ways to do it, and
picking the right one is mostly a question of *what kind of rule* you have.
| Your rule is about… | Use |
|---|---|
| Whether an **operation** may happen — a purchase limit, B2B eligibility, a region policy | A workflow [`validate` hook](/developer/customization/workflows) |
| The **shape of a record** — a field you added must be present, a format must match | A [decorator](/developer/customization/decorators) adding a validation |
| A **new attribute** you need on an existing model | [Custom fields](/developer/core-concepts/metafields) |
Spree deliberately has no registry for adding or removing arbitrary model
validations. Adding one with a decorator is already a single line of ordinary
Rails, and removing a core rule is served by the knobs below.
## Vetoing an operation
This is the one to reach for first. A `validate` hook runs inside the flow,
before anything is written, and can stop it:
```ruby
# config/initializers/spree.rb
Spree.hooks.register('carts.add_item.validate', 'MyStore::CheckPurchaseLimit')
Spree.hooks.register('carts.upsert_items.validate', 'MyStore::CheckPurchaseLimit')
module MyStore
class CheckPurchaseLimit
def call(workflow)
return if workflow.quantity <= 10
workflow.errors.add(:quantity, :purchase_limit_exceeded,
message: 'You can order at most 10 of this item.')
workflow.reject!
end
end
end
```
Why this beats a model validation for operational rules: it runs only for the
operation you targeted, so a data migration or an admin correction isn't fought
by a customer-facing rule; it sees the whole flow, not one record; and it can
tell staff from customers (`workflow.created_by`) to allow a supervisor
override.
Both cart keys appear above because adding to a cart and setting a quantity are
different flows. See [Services & Workflows](/developer/customization/workflows)
for the full hook list.
## Relaxing a rule Spree ships
Never call `clear_validators!` — it wipes every validation on the model,
including ones added by other extensions, and the breakage appears far from the
cause. Use one of these instead.
### Store preferences
Some rules are switchable per store, with no code at all. Change them in the
dashboard under **Settings → Store**, or through the Admin API:
| Preference | Effect |
|---|---|
| `address_requires_phone` | Requires a phone number on addresses |
| `company_field_enabled` | Shows the company field on address forms |
| `address_requires_company` | Requires it — only meaningful with the field shown |
| `disable_sku_validation` | Turns off SKU uniqueness |
<CodeGroup>
```typescript Admin SDK
await adminClient.store.update({
address_requires_phone: false,
})
```
```bash cURL
curl -X PATCH 'https://api.mystore.com/api/v3/admin/store' \
-H 'X-Spree-API-Key: sk_xxx' \
-H 'Content-Type: application/json' \
-d '{ "address_requires_phone": false }'
```
</CodeGroup>
<Note>
All four are editable in the dashboard except `address_requires_company`, which
is API-only for now.
</Note>
### The address validator registry
Address rules are regional and business-specific, so addresses carry a registry
of extra validator classes you can add to and remove from:
```ruby
# server/config/initializers/spree.rb — or config.to_prepare for your own classes
Spree.validators.addresses.register(MyStore::PostBoxValidator)
# Drop a rule Spree ships
Spree.validators.addresses.unregister(Spree::Addresses::PhoneValidator)
```
A validator is an ordinary `ActiveModel::Validator`:
```ruby
module MyStore
class PostBoxValidator < ActiveModel::Validator
def validate(record)
return unless record.address1.to_s.match?(/\A\s*P\.?O\.? Box/i)
record.errors.add(:address1, :po_box_not_deliverable)
end
end
end
```
Register your own classes from `config.to_prepare` rather than an initializer —
the registry holds classes, and a reloadable constant registered once at boot
goes stale on the next reload.
## Checkout requirements
Rules about what a cart needs *before it can be completed* — a phone number
before delivery, a purchase order number for B2B — belong in the checkout
requirements registry rather than a model validation, because they also drive
what the storefront shows as outstanding:
```ruby
Spree::Checkout::Registry.add_requirement(
step: 'address',
field: 'phone',
message: 'Phone number is required for delivery',
satisfied: ->(cart) { cart.ship_address&.phone.present? }
)
```
See the [customization quickstart](/developer/customization/quickstart) for the full registry API.
## Custom field values
Custom fields currently validate their type only — a `Number` field rejects
non-numbers, a `Json` field rejects malformed JSON. There is no per-definition
length, range or format rule yet. A product type marking a custom field as
*required* is an advisory marker shown in the dashboard; the server does not
enforce it.