Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Let extensions insert their own fulfillment statuses

Damian Legawiecc390da022c22
diff --git a/docs/v6/developer/core-concepts/fulfillments.mdx b/docs/v6/developer/core-concepts/fulfillments.mdx
index 8699fe412d..4ba05f7f31 100644
--- a/docs/v6/developer/core-concepts/fulfillments.mdx
+++ b/docs/v6/developer/core-concepts/fulfillments.mdx
@@ -157,6 +157,15 @@ await adminClient.orders.fulfillments.update('or_xxx', 'ful_xxx', {
})
await adminClient.orders.fulfillments.fulfill('or_xxx', 'ful_xxx')
+// Ship only some of it — the chosen units split off and ship,
+// the rest stays open
+await adminClient.orders.fulfillments.fulfill('or_xxx', 'ful_xxx', {
+ items: [{ item_id: 'li_xxx', quantity: 1 }],
+})
+
+// Ship against an unpaid invoice — your call, not the API's
+await adminClient.orders.fulfillments.fulfill('or_xxx', 'ful_xxx', { force: true })
+
// Record receipt yourself when no carrier reports it for you
await adminClient.orders.fulfillments.markDelivered('or_xxx', 'ful_xxx')
@@ -209,6 +218,63 @@ Delivery is priced either by a rule you configure in the dashboard — flat rate
Methods can also carry conditions that decide when they're offered at all: free shipping over a certain order value, or heavy items excluded from letter post. These are applied in one place, so both kinds of pricing respect them.
+## Adding your own statuses
+
+A made-to-order business — print on demand, furniture built after purchase —
+has a stage between "order placed" and "handed to the carrier". There are two
+ways to model it, and the lighter one is usually right.
+
+**Track production in your own model, gate handover with a hook.** A production
+pipeline usually has more resolution than one word — queued, printing, quality
+check, packed — and that detail belongs in your own tables or your
+integration's metadata, not in the parcel's lifecycle vocabulary. What core
+needs to know is only *whether the parcel may go out yet*, and that is exactly
+what the fulfill workflow's validate hook expresses:
+
+```ruby
+Spree.hooks.register('fulfillments.fulfill.validate') do |flow|
+ work_order = MyApp::WorkOrder.find_by(fulfillment: flow.fulfillment)
+ flow.reject!('still in production') unless work_order&.completed?
+end
+```
+
+The fulfillment stays `unfulfilled` while you build the thing; your storefront
+renders "we're making your furniture" as presentation, the same way pickup
+orders render `fulfilled` as "ready for pickup".
+
+**Add a real status when merchants need to act on the stage.** If staff filter
+by it, reports group by it, or webhooks fire on entering it, make it a
+first-class status:
+
+```ruby
+# an initializer
+Spree::Fulfillment.add_status('in_production', after: 'unfulfilled')
+```
+
+That gives you the `in_production?` predicate, the `.in_production` scope and
+a valid value. Moving into it is deliberately not declarative — write a small
+workflow, which is also where the printer submission or the workshop handoff
+belongs:
+
+```ruby
+class MyApp::Fulfillments::StartProduction < Spree::Workflow
+ def perform(fulfillment:)
+ super
+ step :ensure_startable # refuse unless fulfillment.unfulfilled?
+ step :mark_in_production # update!(status: 'in_production') + publish an event
+ external_step :submit_to_printer
+ success(fulfillment.reload)
+ end
+end
+```
+
+Core's own actions keep working on your status without overrides: the guards
+ask whether the parcel has *already gone out*, not whether it holds one of the
+built-in values, so an `in_production` fulfillment can still be fulfilled or
+canceled. Statuses are additive only — core workflows guard on core statuses,
+so removing one would silently break them — and confirmed receipt still only
+follows handover.
+
## Events
Fulfillments publish [events](/developer/core-concepts/events) — `fulfillment.created`, `fulfillment.fulfilled`, `fulfillment.delivered`, `fulfillment.canceled` — which also reach [webhooks](/developer/core-concepts/webhooks). Use them to notify a customer, push to a warehouse system, or send tracking emails.
diff --git a/spree/core/app/models/spree/fulfillment.rb b/spree/core/app/models/spree/fulfillment.rb
index 0c289b8af0..df70bf5d60 100644
--- a/spree/core/app/models/spree/fulfillment.rb
+++ b/spree/core/app/models/spree/fulfillment.rb
@@ -146,14 +146,23 @@ module Spree
# rule with the provider's own veto; the payment and stock side of the
# question belongs to Spree::Fulfillments::Fulfill, which can report why.
#
+ # Stated negatively — anything that has not already gone out can go out —
+ # so a status an extension adds before `fulfilled` (an `in_production`
+ # stage, say) is fulfillable without overriding anything. Whether it
+ # SHOULD go out yet is the fulfill workflow's validate hook's question.
+ #
# @return [Boolean]
def can_fulfill?
- (unfulfilled? || canceled?) && provider.can_fulfill?(self)
+ !fulfilled_or_delivered? && provider.can_fulfill?(self)
end
- # @return [Boolean] whether the package can still be recalled
+ # Whether the package can still be recalled: anything that has neither
+ # gone out nor already been recalled. Negative for the same reason as
+ # {#can_fulfill?} — custom pre-handover statuses stay cancelable.
+ #
+ # @return [Boolean]
def can_cancel?
- unfulfilled?
+ !fulfilled_or_delivered? && !canceled?
end
# @return [Boolean] whether a canceled fulfillment can be reinstated
diff --git a/spree/core/spec/models/spree/shipment_spec.rb b/spree/core/spec/models/spree/shipment_spec.rb
index 3553e7edd1..2cd24251aa 100644
--- a/spree/core/spec/models/spree/shipment_spec.rb
+++ b/spree/core/spec/models/spree/shipment_spec.rb
@@ -135,6 +135,45 @@ describe Spree::Shipment, type: :model do
end
end
+ # The guards are stated negatively — anything not yet handed over can be
+ # fulfilled or canceled — precisely so a status an extension inserts before
+ # `fulfilled` works with the core workflows out of the box.
+ describe 'an added custom status' do
+ around do |example|
+ original = Spree::Fulfillment.statuses
+ Spree::Fulfillment.add_status('in_production', after: 'unfulfilled')
+ example.run
+ ensure
+ Spree::Fulfillment.statuses = original
+ end
+
+ it 'is valid, with a predicate and a scope' do
+ shipment.status = 'in_production'
+
+ expect(shipment).to be_valid
+ expect(shipment).to be_in_production
+ expect(Spree::Fulfillment.statuses).to include('in_production')
+ end
+
+ it 'can still be handed over' do
+ shipment.update!(status: 'in_production')
+
+ expect(shipment.can_fulfill?).to be true
+ end
+
+ it 'can still be recalled' do
+ shipment.update!(status: 'in_production')
+
+ expect(shipment.can_cancel?).to be true
+ end
+
+ it 'cannot skip straight to confirmed receipt' do
+ shipment.update!(status: 'in_production')
+
+ expect(shipment.can_mark_delivered?).to be false
+ end
+ end
+
describe 'tracking_status' do
it 'accepts a carrier status' do
shipment.tracking_status = 'in_transit'