Order Item

First-Pass Node Dossier

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

What It Is

OrderItem is the line-level commercial and fulfillment unit inside an order. It stores the ordered product or custom item, quantity, price, discount, shipping linkage, fulfillment state, and refundability context.

Parent hierarchy:

• Order Lifecycle
• Order Authoring And Review
• Order Item

Primary implementation paths:

• packages/framework/src/Models/OrderItem.php
• packages/framework/src/Http/Controllers/Api/Admin/OrderItemsController.php
• packages/framework/src/Http/Controllers/Api/Storefront/CartItemsController.php
• packages/framework/src/Actions/OrderItem
• packages/framework/src/Actions/Storefront/OrderItem

What Users Can Do With It

Direct capabilities

Operators can:

• list, create, update, and delete order items under an order
• attach product offers or custom item fields
• change quantity, pricing, discount, and shipping linkage within validation rules
• calculate the refundable amount for a selected quantity
• move items between operational states such as backorder, hold-until-payment, or ship-when-ready

Shoppers can:

• add items to cart
• update cart quantities
• remove items from cart
• set ship_when_ready

Indirect capabilities

Other workflows use OrderItem for:

• shipping-line calculation
• shipment grouping
• fulfillment-request allocation
• refunds and returns
• sample-order enforcement

Things users cannot do directly

This pass did not find a standalone packaged operator page dedicated only to order-item lifecycle management. In practice, order items are edited through the admin order page and storefront cart flows.

Where It Is Managed

Channel	Role	Notes
Admin order items API	Direct	Full nested CRUD under an order
Admin order page	Direct	Main packaged operator UI through the items table
Storefront cart items API	Direct	Add, update, and remove cart items
Storefront cart UI	Direct	Quantity, notices, ship-when-ready, delete
Refund and return flows	Indirect	Refundability and return quantities depend on item state

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/OrderItemsController.php
• packages/framework/src/Http/Controllers/Api/Storefront/CartItemsController.php
• packages/storefront/src/Livewire/Storefront/Cart/Items

Channel-Level Field Coverage

Admin create flow

Admin item creation supports:

• product_id
• product_offer_id
• product_inventory_item_id
• product_inventory_location_id
• product_type_id
• title
• sku
• quantity
• price
• cost
• discount_each
• requires_shipping
• taxable
• custom pricing-measure fields
• dimensional fields
• backorder_until

In the packaged admin order page, operators now have a dedicated Custom item dialog for productless lines. That flow writes:

• product_id as null
• product_type_id
• title
• sku
• quantity
• price
• cost
• requires_shipping
• taxable
• note

Apps can optionally lock this dialog to a fixed item-code option list by overriding the dialog component.

Source:

• packages/framework/src/Actions/OrderItem/CreateOrderItem.php

Admin update flow

The shared update action supports:

• offer and inventory references
• shipping service and shipping line linkage
• title
• sku
• price
• cost
• discount_each
• requires_shipping
• taxable
• dimensional fields
• hold_until_payment
• ship_when_ready
• special_order
• special_cost
• special_cost_note
• hold_until
• reserved_until
• backorder_until
• note
• pricing-measure fields
• quantity

In packaged admin item edit, product-backed lines keep identity fields locked, while productless custom lines can update:

• title
• sku
• product_type_id
• quantity
• price
• cost
• taxable
• requires_shipping
• note

Apps can also provide fixed custom-item options in the edit dialog through component overrides.

Source:

• packages/framework/src/Actions/OrderItem/UpdateOrderItem.php

Storefront create and update flow

Storefront item creation and update enforce:

• valid product and offer IDs
• quantity minimum and maximum rules
• backorder-allowed quantity rules
• optional shipping_method_id
• optional ship_when_ready

Sources:

• packages/framework/src/Actions/Storefront/OrderItem/CreateOrderItem.php
• packages/framework/src/Actions/Storefront/OrderItem/UpdateOrderItem.php

Configuration And Data Model

Key model characteristics:

• soft-deletable
• ERP-syncable
• price-history aware
• sortable within the order
• tax-aware

Important relationships:

• order()
• product()
• productOffer()
• productInventoryItem()
• productInventoryLocation()
• shippingService()
• orderShippingLine()
• orderShipment()
• discountLines()
• orderReturnItems()
• fulfillmentRequestItems()
• fulfillmentItems()

Source:

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

Relationships

OrderItem directly bridges:

• product data
• shipping selection
• fulfillment allocation
• returns
• refunds

Practical dependents:

• cart item rows
• admin items table
• shipment grouping
• return quantity validation

Rules And Downstream Effects

Sample-order rules

The create and update actions enforce sample consistency:

• no sample items on a regular order
• no regular items on a sample order

Sources:

• packages/framework/src/Actions/OrderItem/CreateOrderItem.php
• packages/framework/src/Actions/OrderItem/UpdateOrderItem.php

Shipping side effects

When an order item changes shipping service:

• the linked shipment can be updated
• the order recalculates shipping lines

Source:

• packages/framework/src/Actions/OrderItem/UpdateOrderItem.php

Refund and backorder side effects

Updating items can:

• calculate refund amounts
• send backorder email when backorder_until changes on an open order
• block quantity reduction below fulfilled or allocated quantities

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/OrderItemsController.php
• packages/framework/src/Actions/OrderItem/UpdateOrderItem.php

Integrations And Automation

Cart and storefront rules

Storefront item creation and update use dedicated quantity-validation rules.

Source:

• packages/framework/src/Actions/Storefront/OrderItem

Fulfillment and returns

Order items are the source line for:

• fulfillment-request items
• fulfillment items
• order-return items

Source:

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

Where It Appears To End Users

OrderItem is visible in both storefront and admin, but usually as part of a larger order view.

Users see it in:

• cart item blocks
• admin order item table
• my-account unfulfilled and fulfilled order details

Current Documentation Takeaways

1. OrderItem is the line-level unit that bridges pricing, shipping, fulfillment, and return recovery.
2. Storefront quantity rules and admin operational edits are different surfaces on the same record.
3. Shipping and return behavior depend heavily on item state, not only on the parent order.

Open Questions