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
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.mdxindex 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 youawait 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 rateMethods 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.+## EventsFulfillments 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.rbindex 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 reinstateddiff --git a/spree/core/spec/models/spree/shipment_spec.rb b/spree/core/spec/models/spree/shipment_spec.rbindex 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 doendend+ # 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' doit 'accepts a carrier status' doshipment.tracking_status = 'in_transit'