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: Customizing Checkout
description: Add your own checkout step or requirement, reorder or remove the built-in ones, and carry your own records onto the order.
---
Spree does not run your checkout — your storefront does. What Spree owns is the list
of things a cart still needs, which it reports on cart reads and enforces when you
complete one. Adding to that list is how you make checkout require something of your
own.
<Note>
For what a cart reports and how to read it, see
[Carts](/developer/core-concepts/carts#checkout-requirements). This page is about
adding to it.
</Note>
## Requirements are the gate, steps are a label
Two things are easy to confuse:
- A **requirement** is enforced. It appears on cart reads while unmet, and completing
a cart recomputes the list and refuses if anything is outstanding.
- A **step** is descriptive. It exists so a storefront can render a progress
indicator. Nothing on the server checks which step a customer is on.
So a requirement is what you reach for when something must be true before an order
exists. A step is only worth adding when your checkout genuinely has a stage the
built-in five don't describe.
## Adding a requirement
When the flow is unchanged and you only need one more condition:
```ruby server/config/initializers/spree.rb
Spree::Checkout::Registry.add_requirement(
step: :address,
field: :vat_number,
message: 'VAT number is required for business orders',
satisfied: ->(cart) { cart.metadata['vat_number'].present? }
)
```
While `satisfied:` returns false the cart reports the requirement and refuses to
complete. Its `code` is derived as `<field>_required` — `vat_number_required` here.
The storefront satisfies it by writing the value into the cart's `metadata`. When the
cart is completed, its `metadata` is copied onto the order — onto every order if the
checkout is split between sellers — so the VAT number is still there after placement as
`order.metadata['vat_number']`.
Pass `applicable:` to scope it. It is checked before `satisfied:`, so a requirement
that doesn't apply never appears at all:
```ruby
applicable: ->(cart) { cart.customer&.company.present? }
```
`message` is stored verbatim — wrap it in `I18n.t` yourself if it needs translating.
## Adding a step
A step bundles its own requirements and says when it is satisfied:
```ruby server/config/initializers/spree.rb
Spree::Checkout::Registry.register_step(
name: :loyalty,
before: :payment,
satisfied: ->(cart) { cart.metadata['loyalty_number'].present? },
requirements: ->(cart) {
[{ step: 'loyalty', field: 'loyalty_number',
message: 'Loyalty number is required' }]
}
)
```
The step now shows up in the cart's `current_step` and `completed_steps`, its
requirements appear in `requirements` while unsatisfied, and completion refuses the
cart until they are met.
Each lambda receives the cart. Placement is controlled by two keywords:
| Keyword | Effect |
|---|---|
| `before:` / `after:` | Place the step next to an existing one. `before:` wins if both are given |
| `applicable:` | Whether the step exists for this cart at all — checked before `satisfied:` |
An unanchored step lands immediately before `complete`. An anchor naming a step this
particular cart doesn't have — `before: :payment` on a free cart — falls back to the
same place.
Unlike an added requirement, a step's `requirements:` lambda may set its own `code:`.
## Reordering or removing built-in steps
```ruby server/config/initializers/spree.rb
# Drop a step from the reported list
Spree::Checkout::Registry.base_steps.delete('confirm')
# Or change when one applies
Spree::Checkout::Registry.base_steps['payment'] = ->(cart) { cart.total > 0 }
# Or reorder wholesale — known names keep their own applicability
Spree::Checkout::Registry.base_step_names = %w[address payment delivery complete]
```
<Warning>
Removing a step removes it from the reported list. It does **not** remove the
requirements filed under it — dropping `payment` does not let an unpaid cart
complete. Requirements and steps are separate on purpose.
</Warning>
## Prefer a requirement to a workflow hook
A [workflow hook](/developer/customization/workflows) on `carts.complete.validate`
can also reject a cart, and there are cases for it — anything needing a network call, or a
decision that only makes sense at the moment of completion.
For anything a customer has to fix, a requirement is better: it is reported on every
cart read, so the storefront can show it while they can still act, rather than failing
at the last step with an error they have to interpret.
## Carrying your own records onto the order
A cart's `metadata` is copied onto the order for you. Records your extension keeps in
its own tables against a cart or its line items are not. Register a cart copier to
bring them across:
```ruby config/initializers/engravings.rb
Spree.cart_copiers << MyApp::CopyEngravings
```
```ruby app/services/my_app/copy_engravings.rb
module MyApp
class CopyEngravings
def self.call(cart:, order:, line_item_map:)
MyApp::Engraving.where(line_item: line_item_map.keys).find_each do |engraving|
engraving.dup.update!(line_item: line_item_map.fetch(engraving.line_item))
end
end
end
end
```
`line_item_map` pairs each cart line item with its copy on the order. Copiers run
whenever a cart becomes an order: at checkout, and when a draft order is created from a
cart (`Spree::Orders::CreateFromCart`, which quoting extensions use). They run inside
that copy's transaction once the order's line items exist, so a copier that raises rolls
the whole copy back, and the cart is left as it was.
The copy commits before the payment is taken. If the payment fails before anything was
captured, the order is deleted rather than rolled back, and the customer's next attempt
runs your copier again on a new order. Once a payment has been captured the order is
kept, and completing it resumes that order without copying again. Tie the copied records
to the order's line items with a dependent or cascading delete, so they go with a deleted
order.
When a checkout spans several sellers, the order is divided after the copy. Line items
keep their ids as they move to each seller's order, so key your records by line item
rather than by order.
### When a guest signs in
A guest's cart is folded into the customer's cart when they sign in, and the guest cart
is then deleted. That is a move, not a copy, so it has its own hook rather than a cart
copier. A guest item the customer's cart did not have moves across with its id; one it
already had is added to the matching item and deleted. `carts.merge.after_items_moved`
runs before those deletions, inside the merge's transaction:
```ruby config/initializers/engravings.rb
Spree.hooks.register('carts.merge.after_items_moved') do |merge|
merge.line_item_map.each do |guest_line_item, line_item|
next if guest_line_item == line_item
MyApp::Engraving.where(line_item: guest_line_item).update_all(line_item_id: line_item.id)
end
end
```
## Related
- [Carts](/developer/core-concepts/carts) — reading requirements and completing a cart
- [Custom fields](/developer/core-concepts/metafields) — storing your own data on a cart
- [Services & Workflows](/developer/customization/workflows) — hooks that run during completion