Orders - TALL Stack E-commerce Framework

Orders represent customer purchases and are central to your e-commerce operations. Shopper provides a comprehensive order management system with support for items, addresses, shipping, refunds, and status tracking.

Models

Shopper uses seven models to manage orders:

Model	Purpose
`Shopper\Core\Models\Order`	The main order with statuses, totals, and foreign keys
`Shopper\Core\Models\OrderItem`	Products in the order with quantity, price, and fulfillment status
`Shopper\Core\Models\OrderAddress`	Billing and shipping addresses snapshot
`Shopper\Core\Models\OrderShipping`	Shipments with carrier, tracking, and delivery dates
`Shopper\Core\Models\OrderShippingEvent`	Tracking events for each shipment (location, status changes)
`Shopper\Core\Models\OrderTaxLine`	Tax breakdown per item or shipment
`Shopper\Core\Models\OrderRefund`	Refund requests with status tracking

The Order model implements Shopper\Core\Models\Contracts\Order and uses SoftDeletes. It is configurable via config/shopper/models.php.

Extending the Model

To add custom behavior, extend the model and update your configuration:

namespace App\Models;

use Shopper\Core\Models\Order as BaseOrder;

class Order extends BaseOrder
{
}

Update config/shopper/models.php:

return [
    'order' => \App\Models\Order::class,
];

Database Schema

Order Table

Column	Type	Nullable	Default	Description
`id`	bigint	no	auto	Primary key
`number`	string(32)	no	-	Order number
`price_amount`	integer	yes	null	Order total in cents
`tax_amount`	integer	yes	null	Total tax in cents
`status`	string(32)	no	new	Order status enum
`payment_status`	string(32)	no	pending	Payment status enum
`shipping_status`	string(32)	no	unfulfilled	Shipping status enum
`currency_code`	string	no	-	Currency code (USD, EUR, etc.)
`notes`	text	yes	null	Order notes
`parent_order_id`	bigint	yes	null	FK to parent order
`payment_method_id`	bigint	yes	null	FK to payment method
`channel_id`	bigint	yes	null	FK to channel
`customer_id`	bigint	yes	null	FK to user
`zone_id`	bigint	yes	null	FK to zone
`billing_address_id`	bigint	yes	null	FK to order address
`shipping_address_id`	bigint	yes	null	FK to order address
`shipping_option_id`	bigint	yes	null	FK to carrier option
`discount_id`	bigint	yes	null	FK to the discount that was redeemed (nullOnDelete)
`discount_code`	string	yes	null	Snapshot of the discount code at placement
`discount_type`	string(32)	yes	null	Snapshot of the discount type (`percentage`/`fixed_amount`)
`discount_value_at_apply`	unsigned int	yes	null	Snapshot of the discount value (cents for fixed amount, raw for percentage)
`discount_currency_code`	char(3)	yes	null	Currency the discount was applied in
`cancelled_at`	timestamp	yes	null	Cancellation date
`archived_at`	timestamp	yes	null	Archive date
`deleted_at`	timestamp	yes	null	Soft delete timestamp
`created_at`	timestamp	yes	null	Creation timestamp
`updated_at`	timestamp	yes	null	Last update timestamp

OrderItem Table

Column	Type	Nullable	Description
`id`	bigint	no	Primary key
`name`	string	yes	Product name at time of purchase
`sku`	string	yes	Product SKU at time of purchase
`quantity`	integer	no	Quantity ordered
`unit_price_amount`	integer	no	Unit price in cents
`tax_amount`	integer	no	Tax amount in cents
`discount_amount`	integer	no	Discount amount in cents
`product_id`	bigint	no	Polymorphic relation ID
`product_type`	string	no	Polymorphic relation type
`order_id`	bigint	no	FK to order
`order_shipping_id`	bigint	yes	FK to order_shipping (shipment)
`fulfillment_status`	string	yes	Fulfillment status enum value

OrderAddress Table

Column	Type	Nullable	Description
`id`	bigint	no	Primary key
`customer_id`	bigint	no	FK to user
`first_name`	string	no	First name
`last_name`	string	no	Last name
`company`	string	yes	Company name
`street_address`	string	no	Street address
`street_address_plus`	string	yes	Additional address line
`postal_code`	string	no	Postal/ZIP code
`city`	string	no	City
`state`	string	yes	State/province/region
`phone`	string	yes	Phone number
`country_name`	string	yes	Country name

OrderShipping Table

Column	Type	Nullable	Description
`id`	bigint	no	Primary key
`status`	string(32)	yes	Shipment status enum
`shipped_at`	datetime	yes	Shipment date
`received_at`	datetime	yes	Delivery date
`returned_at`	datetime	yes	Return date
`tracking_number`	string	yes	Carrier tracking number
`tracking_url`	string	yes	Tracking URL
`voucher`	json	yes	Shipping voucher data
`order_id`	bigint	no	FK to order
`carrier_id`	bigint	yes	FK to carrier

OrderRefund Table

Column	Type	Nullable	Description
`id`	bigint	no	Primary key
`refund_reason`	string	yes	Refund reason
`refund_amount`	integer	yes	Refund amount (in cents)
`status`	string	no	Refund status enum
`currency`	string	no	Currency code
`notes`	string	yes	Admin notes
`order_id`	bigint	no	FK to order
`user_id`	bigint	yes	FK to user processing refund

Order Status

Every order tracks three independent statuses: order status, payment status, and shipping status. This separation allows each aspect of the order to progress independently. For example, an order can be paid before it’s shipped, or partially shipped while still processing.

Order Status

The OrderStatus enum tracks the overall lifecycle of the order:

use Shopper\Core\Enum\OrderStatus;

OrderStatus::New         // new (default)
OrderStatus::Processing  // processing
OrderStatus::Completed   // completed
OrderStatus::Cancelled   // cancelled
OrderStatus::Archived    // archived

Status	Database Value	Color	Description
New	`new`	info	Newly placed order
Processing	`processing`	primary	Order is being prepared
Completed	`completed`	teal	Order fulfilled and delivered
Cancelled	`cancelled`	danger	Order cancelled
Archived	`archived`	gray	Removed from active list

Payment Status

The PaymentStatus enum tracks whether payment has been collected. It is updated automatically by the PaymentProcessingService as transactions succeed.

use Shopper\Core\Enum\PaymentStatus;

PaymentStatus::Pending             // pending (default)
PaymentStatus::Authorized          // authorized
PaymentStatus::Paid                // paid
PaymentStatus::PartiallyRefunded   // partially_refunded
PaymentStatus::Refunded            // refunded
PaymentStatus::Voided              // voided

Status	Database Value	Color	Description
Pending	`pending`	warning	Awaiting payment
Authorized	`authorized`	info	Funds held, not yet captured
Paid	`paid`	success	Funds collected
Partially Refunded	`partially_refunded`	orange	Some amount refunded
Refunded	`refunded`	gray	Full amount refunded
Voided	`voided`	danger	Cancelled before capture

For the full payment lifecycle, capture strategies, and transaction recording, see the Payments page.

Shipping Status

The ShippingStatus enum tracks the overall shipping state at the order level. It reflects the combined state of all shipments on the order.

use Shopper\Core\Enum\ShippingStatus;

ShippingStatus::Unfulfilled        // unfulfilled (default)
ShippingStatus::PartiallyShipped   // partially_shipped
ShippingStatus::Shipped            // shipped
ShippingStatus::PartiallyDelivered // partially_delivered
ShippingStatus::Delivered          // delivered
ShippingStatus::PartiallyReturned  // partially_returned
ShippingStatus::Returned           // returned

Status	Database Value	Color	Description
Unfulfilled	`unfulfilled`	warning	No items shipped yet
Partially Shipped	`partially_shipped`	info	Some items shipped
Shipped	`shipped`	indigo	All items shipped
Partially Delivered	`partially_delivered`	primary	Some packages delivered
Delivered	`delivered`	success	All packages delivered
Partially Returned	`partially_returned`	orange	Some items returned
Returned	`returned`	gray	All items returned

For shipment-level tracking (individual packages with carriers and tracking numbers), see the Fulfillment page.

Status Check Methods

$order->isNew();               // true if status is New
$order->isProcessing();        // true if status is Processing
$order->isCompleted();         // true if status is Completed
$order->isArchived();          // true if status is Archived
$order->isNotCancelled();      // true if status is NOT Cancelled
$order->canBeCancelled();      // true if not Cancelled/Archived and shipping is Unfulfilled

$order->isPaid();              // true if payment_status is Paid
$order->isPaymentPending();    // true if payment_status is Pending
$order->isPaymentAuthorized(); // true if payment_status is Authorized
$order->isRefunded();          // true if payment_status is Refunded

$order->isShipped();           // true if shipping_status is Shipped
$order->isShippingPending();   // true if shipping_status is Unfulfilled

Fulfillment Status

The FulfillmentStatus enum tracks individual item fulfillment, enabling partial shipments and multi-carrier delivery:

use Shopper\Core\Enum\FulfillmentStatus;

FulfillmentStatus::Pending              // pending
FulfillmentStatus::ForwardedToSupplier  // forwarded_to_supplier (dropshipping)
FulfillmentStatus::Processing           // processing
FulfillmentStatus::Shipped              // shipped
FulfillmentStatus::Delivered            // delivered
FulfillmentStatus::Cancelled            // cancelled

Status	Database Value	Color	Description
Pending	`pending`	warning	Awaiting processing
Forwarded to Supplier	`forwarded_to_supplier`	info	Sent to external supplier (dropshipping)
Processing	`processing`	primary	Being prepared
Shipped	`shipped`	indigo	In transit
Delivered	`delivered`	success	Received by customer
Cancelled	`cancelled`	danger	Fulfillment cancelled

FulfillmentStatus is applied per item, not per order. This allows partial fulfillment when items ship at different times or from different carriers. See the Fulfillment page for complete workflows.

Refund Status

The OrderRefundStatus enum defines refund states:

use Shopper\Core\Enum\OrderRefundStatus;

OrderRefundStatus::Pending        // pending (default)
OrderRefundStatus::Awaiting       // awaiting
OrderRefundStatus::Treatment      // treatment
OrderRefundStatus::Partial_Refund // partial_refund
OrderRefundStatus::Refunded       // refunded
OrderRefundStatus::Rejected       // rejected
OrderRefundStatus::Cancelled      // cancelled

Relationships

Customer

$order->customer;

Order::query()
    ->where('customer_id', $userId)
    ->get();

Items

$order->items;

To add an item to an order, retrieve the product price for the order’s currency:

$price = $product->getPrice('USD');

$order->items()->create([
    'name' => $product->name,
    'sku' => $product->sku,
    'quantity' => 2,
    'unit_price_amount' => $price->amount,
    'product_id' => $product->id,
    'product_type' => $product->getMorphClass(),
]);

Addresses

$order->shippingAddress;
$order->billingAddress;
$order->shippingAddress->full_name;

Shipping

$order->shippingOption;
$order->shippings;

To create a shipment and link items:

$shipment = $order->shippings()->create([
    'carrier_id' => $carrierId,
    'shipped_at' => now(),
    'tracking_number' => 'TRACK123456',
    'tracking_url' => 'https://carrier.com/track/TRACK123456',
]);

$order->items()
    ->whereIn('id', [$itemId1, $itemId2])
    ->update([
        'order_shipping_id' => $shipment->id,
        'fulfillment_status' => FulfillmentStatus::Shipped,
    ]);

Item Shipment

$item->shipment;
$item->shipment?->carrier;
$shipment->items;

For complete multi-shipment and dropshipping workflows, see the Fulfillment page.

Refund

$order->refund;

To create a refund:

$order->refund()->create([
    'refund_reason' => 'Product damaged',
    'refund_amount' => $order->total(),
    'currency' => $order->currency_code,
    'status' => OrderRefundStatus::Pending,
]);

Channel and Zone

$order->channel;
$order->zone;

Discount

Orders snapshot the discount that was redeemed at placement time. The discount_id foreign key still resolves the original Discount model while it exists, but the four snapshot columns (discount_code, discount_type, discount_value_at_apply, discount_currency_code) preserve the data even after the originating discount is edited or deleted. This follows the Shopify pattern of immutable order records.

$order->discount;
$order->discount_code;
$order->discount_type;
$order->discount_value_at_apply;
$order->discount_currency_code;

To find every order that redeemed a given discount, use the same query Shopper uses internally to enforce the per-user usage limit:

use Shopper\Models\Order;

Order::query()
    ->where('discount_id', $discount->id)
    ->where('customer_id', $customerId)
    ->exists();

For the full validation and atomic reservation rules, see Usage Limit Enforcement on the Discounts page.

Parent/Child Orders

For split orders, an order can have a parent and children:

$order->parent;
$order->children;

Computed Values

Order Total

The total() method returns the sum of all item totals in cents:

$order->total();

Events

Order lifecycle events are dispatched automatically throughout the order lifecycle:

use Shopper\Core\Events\Orders\OrderCreated;
use Shopper\Core\Events\Orders\OrderPaid;
use Shopper\Core\Events\Orders\OrderShipped;
use Shopper\Core\Events\Orders\OrderCompleted;
use Shopper\Core\Events\Orders\OrderCancelled;
use Shopper\Core\Events\Orders\OrderArchived;
use Shopper\Core\Events\Orders\OrderDeleted;
use Shopper\Core\Events\Orders\OrderShipmentCreated;
use Shopper\Core\Events\Orders\OrderShipmentDelivered;
use Shopper\Core\Events\Orders\OrderNoteAdded;

For the full events reference including shipment events, payload details, and usage examples, see the Events page.

Creating Orders

Basic Order

use Shopper\Core\Models\Order;
use Shopper\Core\Enum\OrderStatus;

$order = Order::query()->create([
    'number' => generate_number(),
    'customer_id' => auth()->id(),
    'currency_code' => current_currency(),
    'channel_id' => $channelId,
    'status' => OrderStatus::New,
]);

Complete Order with Items and Addresses

Create the shipping and billing addresses:

$shippingAddress = OrderAddress::query()->create([
    'customer_id' => auth()->id(),
    'first_name' => 'John',
    'last_name' => 'Doe',
    'street_address' => '123 Main St',
    'city' => 'New York',
    'postal_code' => '10001',
    'country_name' => 'United States',
    'phone' => '+1234567890',
]);

$billingAddress = OrderAddress::query()->create([
    'customer_id' => auth()->id(),
    'first_name' => 'John',
    'last_name' => 'Doe',
    'street_address' => '123 Main St',
    'city' => 'New York',
    'postal_code' => '10001',
    'country_name' => 'United States',
]);

$order = Order::query()->create([
    'number' => generate_number(),
    'customer_id' => auth()->id(),
    'currency_code' => 'USD',
    'shipping_address_id' => $shippingAddress->id,
    'billing_address_id' => $billingAddress->id,
    'shipping_option_id' => $carrierOptionId,
    'zone_id' => $zoneId,
]);

foreach ($cart->items as $cartItem) {
    $price = $cartItem->product->getPrice($order->currency_code);

    $order->items()->create([
        'name' => $cartItem->product->name,
        'sku' => $cartItem->product->sku,
        'quantity' => $cartItem->quantity,
        'unit_price_amount' => $price->amount,
        'product_id' => $cartItem->product->id,
        'product_type' => $cartItem->product->getMorphClass(),
    ]);
}

Query Scopes

The Order model provides two scopes for filtering by archive status:

Order::query()->archived()->get();     // Only archived orders
Order::query()->notArchived()->get();  // Exclude archived orders

Retrieving Orders

To get all non-archived orders with their relationships:

use Shopper\Core\Models\Order;

$orders = Order::query()
    ->with(['customer', 'items', 'shippingAddress'])
    ->latest()
    ->get();

$newOrders = Order::query()
    ->where('status', OrderStatus::New)
    ->get();

Query orders by customer with pagination:

$customerOrders = Order::query()
    ->where('customer_id', $customerId)
    ->with('items.product')
    ->latest()
    ->paginate(10);

Find an order by number:

$order = Order::query()
    ->where('number', $orderNumber)
    ->with(['items', 'shippingAddress', 'billingAddress', 'refund'])
    ->firstOrFail();

Order Number Generation

Use the generate_number() helper to create unique order numbers:

$orderNumber = generate_number();

This returns a formatted string like ORD-20260327-001234. The format is configurable in config/shopper/orders.php.

Permissions

The admin panel generates five permissions for order management:

Permission	Description
`browse_orders`	View the orders list
`read_orders`	View a single order detail
`add_orders`	Create new orders
`edit_orders`	Edit existing orders
`delete_orders`	Delete orders

Components

To customize the admin UI for order management:

php artisan shopper:component:publish order

Creates config/shopper/components/order.php:

use Shopper\Livewire;

return [
    'pages' => [
        'order-index' => Livewire\Pages\Order\Index::class,
        'order-detail' => Livewire\Pages\Order\Detail::class,
        'order-shipments' => Livewire\Pages\Order\Shipments::class,
        'order-abandoned-carts' => Livewire\Pages\Order\AbandonedCarts::class,
    ],
    'components' => [
        'order-customer' => Livewire\Components\Orders\OrderCustomer::class,
        'order-fulfillment' => Livewire\Components\Orders\Fulfillment::class,
        'order-items' => Livewire\Components\Orders\OrderItems::class,
        'order-notes' => Livewire\Components\Orders\OrderNotes::class,
        'order-summary' => Livewire\Components\Orders\OrderSummary::class,

        'slide-overs.create-shipping-label' => Livewire\SlideOvers\CreateShippingLabel::class,
        'slide-overs.shipment-add-event' => Livewire\SlideOvers\ShipmentAddEvent::class,
        'slide-overs.shipment-detail' => Livewire\SlideOvers\ShipmentDetail::class,
        'slide-overs.abandoned-cart-detail' => Livewire\SlideOvers\AbandonedCartDetail::class,
    ],
];

Storefront Example

In most cases, orders are created automatically when a cart is converted via CreateOrderFromCartAction. You rarely need to create orders manually. Here is how the checkout flow and order display work:

namespace App\Http\Controllers;

use Shopper\Cart\Actions\CreateOrderFromCartAction;
use Shopper\Cart\Facades\Cart;
use Shopper\Core\Models\Order;

class CheckoutController extends Controller
{
    public function store()
    {
        $order = resolve(CreateOrderFromCartAction::class)
            ->execute(Cart::current());

        Cart::forget();

        return redirect()->route('orders.show', $order);
    }

    public function show(Order $order)
    {
        abort_unless($order->customer_id === auth()->id(), 403);

        return view('orders.show', [
            'order' => $order->load(['items.product', 'shippingAddress', 'billingAddress']),
        ]);
    }
}

The CreateOrderFromCartAction handles everything in a single transaction: calculating totals, creating addresses, creating order items, applying discounts, computing taxes, and marking the cart as completed. See the Cart page for details.

Order Status Flow

From Status	Possible Transitions
New	Processing, Cancelled, Archived
Processing	Completed, Cancelled
Completed	Archived
Cancelled	(terminal state)
Archived	(terminal state)

​Models

​Extending the Model

​Database Schema

​Order Table

​OrderItem Table

​OrderAddress Table

​OrderShipping Table

​OrderRefund Table

​Order Status

​Order Status

​Payment Status

​Shipping Status

​Status Check Methods

​Fulfillment Status

​Refund Status

​Relationships

​Customer

​Items

​Addresses

​Shipping

​Item Shipment

​Refund

​Channel and Zone

​Discount

​Parent/Child Orders

​Computed Values

​Order Total

​Events

​Creating Orders

​Basic Order

​Complete Order with Items and Addresses

​Query Scopes

​Retrieving Orders

​Order Number Generation

​Permissions

​Components

​Storefront Example

​Order Status Flow

Models

Extending the Model

Database Schema

Order Table

OrderItem Table

OrderAddress Table

OrderShipping Table

OrderRefund Table

Order Status

Order Status

Payment Status

Shipping Status

Status Check Methods

Fulfillment Status

Refund Status

Relationships

Customer

Items

Addresses

Shipping

Item Shipment

Refund

Channel and Zone

Discount

Parent/Child Orders

Computed Values

Order Total

Events

Creating Orders

Basic Order

Complete Order with Items and Addresses

Query Scopes

Retrieving Orders

Order Number Generation

Permissions

Components

Storefront Example

Order Status Flow