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
canonical: "https://spreecommerce.org/docs/developer/customization/validations"
---
## 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](/v5/developer/customization/workflows) |
| The **shape of a record** — a field you added must be present, a format must match | A [decorator](/v5/developer/customization/decorators) adding a validation |
| A **new attribute** you need on an existing model | [Custom fields](/v5/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](/v5/developer/customization/workflows)
for the full hook list.
## Adding a rule to a model
For rules about the shape of a record, a decorator is the supported route:
```ruby
# app/models/spree/product_decorator.rb
module MyStore
module ProductDecorator
def self.prepended(base)
base.validates :external_id, presence: true, uniqueness: true
end
end
end
Spree::Product.prepend(MyStore::ProductDecorator)
```
Decorators couple you to Spree internals, so prefer a hook when the rule is
really about an operation. See
[Decorators](/v5/developer/customization/decorators).
## 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 already switchable, per store, from the dashboard or a console:
| 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 |
```ruby
store.update!(preferred_address_requires_company: true)
```
### Overriding the gating predicate
Most conditional validations in `Spree::Address` are gated on a predicate you
can override, which is far safer than removing the validation:
```ruby
module MyStore
module AddressDecorator
# Business addresses only in this store.
def require_company?
!quick_checkout
end
end
end
Spree::Address.prepend(MyStore::AddressDecorator)
```
`require_name?`, `require_street?`, `require_zipcode?`, `require_phone?` and
`require_company?` all work this way.
### 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
# 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 [Spree 6 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.