Fulfillment Request

First-Pass Node Dossier

This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.

What It Is

FulfillmentRequest is the planning and coordination record that groups order items by inventory location for vendor communication, scheduling, confirmation, and eventual fulfillment.

Parent hierarchy:

• Fulfillment & Shipping
• Fulfillment Planning And Coordination
• Fulfillment Request

Primary implementation paths:

• packages/framework/src/Models/FulfillmentRequest.php
• packages/framework/src/Actions/FulfillmentRequest
• packages/framework/src/Http/Controllers/Api/Admin/FulfillmentRequestsController.php
• packages/framework/src/Actions/FulfillmentRequest/Requests/Admin

What Users Can Do With It

Direct capabilities

Operators can:

• create, show, update, and delete fulfillment requests through the admin API
• set or revise shipping details, notes, scheduling state, and transfer locations
• calculate the request
• confirm request items
• fulfill confirmed items
• cancel request items
• mark delivery booked
• send fulfillment requests, quote emails, schedule-delivery emails, and pickup details
• download request PDFs, packing slips, quote PDFs, and estimated invoices

Indirect capabilities

Other workflows also create or change fulfillment requests:

• order auto-assignment of fulfillment-request items
• observer-driven recalculation when the request or its items change
• transfer-location updates and quote uploads
• fulfillment creation and subsequent order recalculation

Things users cannot do directly

Where It Is Managed

Channel	Role	Notes
Admin API	Direct	Main CRUD plus many specialized actions
Notifications and action requests	Indirect	Pending fulfillment actions surface through notifications
Customer email workflows	Indirect	Request state can send customer-facing scheduling or pickup emails
Storefront	Indirect	Customers mainly experience downstream fulfillments rather than the request itself

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/FulfillmentRequestsController.php
• packages/framework/routes/admin.php

Channel-Level Field Coverage

Create payload

Creating a fulfillment request requires:

• order_id
• product_inventory_location_id
• optional internal_note

Creation also copies:

• shipping address JSON from the order
• preferred delivery date from the order hold-until date
• project number from the order

Source:

• packages/framework/src/Actions/FulfillmentRequest/CreateFulfillmentRequest.php

Update payload

The update action supports a broad operational field set, including:

• notes and project number
• carrier name, type, method, and reference number
• pickup and estimated-delivery dates
• transfer-location IDs
• confirmation numbers
• shipping-booked and pickup-confirmed state
• scheduling approval flags
• waiting-for-details flags
• delivery timing issue reason and note
• shipping address JSON validation

Source:

• packages/framework/src/Actions/FulfillmentRequest/UpdateFulfillmentRequest.php

List and show payloads

The admin index and show actions support rich includes around:

• order and customer
• product inventory location
• transfer locations
• fulfillment-request items
• order shipping lines
• comments
• flags
• delivery timing issue
• fulfillments and fulfillment items

Sources:

• packages/framework/src/Actions/FulfillmentRequest/Requests/Admin/Index.php
• packages/framework/src/Actions/FulfillmentRequest/Requests/Admin/Show.php
• packages/framework/src/Http/Resources/Admin/FulfillmentRequestResource.php

Configuration And Data Model

Key model characteristics:

• soft-deletable
• searchable
• flag-aware
• action-request aware
• activity-log aware
• commentable

Important relationships:

• order()
• productInventoryLocation()
• transferLocations()
• fulfillmentRequestItems()
• fulfillments()
• comments()
• fulfillmentServiceRequests()
• deliveryTimingIssue()

Operational note:

• this node is the planning record; item-level detail, transfer details, and final fulfillment outputs all hang off it

Source:

• packages/framework/src/Models/FulfillmentRequest.php

Rules And Downstream Effects

Booking, scheduling, and validation rules

The update action enforces rules such as:

• no location change after fulfilled quantities already exist
• no booking without scheduling approval for scheduled delivery
• waiting-for-delivery-details cannot be cleared without an estimated delivery date in certain cases
• shipping address JSON must validate against real postal-code and province data

Source:

• packages/framework/src/Actions/FulfillmentRequest/UpdateFulfillmentRequest.php

Confirmation rules

A request cannot be confirmed unless it has:

• an estimated delivery date
• a shipping pickup date
• transfer-location pickup and estimated-delivery dates for each transfer, when transfers exist
• a confirmation number

Source:

• packages/framework/src/Actions/FulfillmentRequest/ConfirmFulfillmentRequestItems.php

Fulfillment rules

Fulfilling items validates:

• confirmed quantity
• unfulfilled quantity
• hold-until-payment constraints
• tracking information

Then it creates a Fulfillment, fulfillment items, recalculates the request, recalculates the order, and emits the fulfillment-confirmed event.

Sources:

• packages/framework/src/Actions/FulfillmentRequest/FulfillFulfillmentRequestItems.php
• packages/framework/src/Actions/Fulfillment/CreateFulfillmentFromFulfillmentRequest.php

Observer-driven recalculation

The request recalculates automatically when:

• the request is created, updated, restored, or force deleted
• related fulfillment-request items are created, updated, deleted, or restored

Sources:

• packages/framework/src/Observers/FulfillmentRequestObserver.php
• packages/framework/src/Observers/FulfillmentRequestItemObserver.php

Integrations And Automation

Customer and vendor emails

Fulfillment requests drive:

• customer schedule-delivery emails
• transfer-pickup emails
• pickup-details emails — the pickup address and note are sourced from the last transfer location in the request's transfer chain when one exists, falling back to the productInventoryLocation when no transfers are present
• vendor quote emails
• fulfillment-request emails

Sources:

• packages/framework/src/Actions/FulfillmentRequest/SendPickupDetails.php
• packages/framework/src/Actions/FulfillmentRequest/Requests/SendVendorQuoteEmail.php
• packages/framework/src/Actions/FulfillmentRequest/Requests/SendScheduleDeliveryEmail.php
• packages/framework/src/Actions/FulfillmentRequest/Http/Api/Admin/SendTransferLocationPickupEmail.php

Documents

This node can generate:

• request PDF
• packing slip PDF
• quote PDF
• estimated invoice PDF

Sources:

• packages/framework/src/Actions/FulfillmentRequest/GeneratePDF.php
• packages/framework/src/Actions/FulfillmentRequest/GeneratePackingSlipPDF.php
• packages/framework/src/Actions/FulfillmentRequest/DownloadQuotePdf.php
• packages/framework/src/Actions/FulfillmentRequest/GenerateEstimatedInvoicePDF.php

Where It Appears To End Users

FulfillmentRequest is mostly an internal operations record.

Customers usually do not browse the request directly in the shared package. Instead they experience:

• scheduling emails
• pickup details
• delivery booking emails
• eventual fulfillment and invoice records

Current Documentation Takeaways

1. FulfillmentRequest is the coordination record between shipping selection and final fulfillment, not the final shipped record itself.
2. Dates, confirmation, transfers, and item quantities all have strong validation rules before a request can move forward.

Open Questions