Orders
Complete reference for the Order model, items, addresses, shipping, refunds, and order management in Shopper.
Orders represent customer purchases and are central to your e-commerce operations. Shopper stores each order with its items, addresses, shipments, refund, and three statuses (order, payment, shipping).
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 | unsigned int | yes | null | Total tax in cents |
status | string(32) | no | - | Order status enum, set to new by the model |
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 |
metadata | jsonb | yes | null | Custom key/value data |
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 | yes | 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 |
reason | text | yes | Refund reason |
amount | integer | no | Refund amount in cents |
status | string | no | Refund status enum |
currency | string | no | Currency code |
notes | text | yes | Admin notes |
metadata | jsonb | yes | Custom key/value data |
order_id | bigint | no | FK to order |
user_id | bigint | yes | FK to user, loaded with $refund->customer |
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 finished |
| 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. In the admin panel, the Mark as paid action of a pending or authorized order sets Paid directly: it does not call the payment driver and records no transaction. On an authorized Stripe payment, use Capture payment instead: once the order is Paid, the capture action is hidden and Shopper never captures the authorization (see Status Transitions).
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. Shopper computes it from the fulfillment status of the order's items each time a shipment is picked up, delivered or returned (Shopper\Core\Actions\SyncOrderShippingStatusAction).
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 no package is delivered or returned
$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 UnfulfilledFulfillment 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 // cancelledRelationships
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($order->currency_code);
$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, link items to it, and record the carrier pickup:
use Shopper\Core\Actions\RecordShipmentEventAction;
use Shopper\Core\Enum\ShipmentStatus;
$shipment = $order->shippings()->create([
'carrier_id' => $carrierId,
'status' => ShipmentStatus::Pending,
'tracking_number' => '1Z999AA10123456784',
'tracking_url' => 'https://www.ups.com/track?tracknum=1Z999AA10123456784',
]);
$order->items()
->whereIn('id', [$itemId1, $itemId2])
->update(['order_shipping_id' => $shipment->id]);
resolve(RecordShipmentEventAction::class)->execute($shipment, ShipmentStatus::PickedUp);Recording PickedUp sets shipped_at, moves the linked items from Pending to Shipped, moves a New order to Processing, and recomputes the order's shipping_status. Create the shipment with the Pending status: a shipment without a status can only move to Pending, so recording PickedUp on it does nothing. Record InTransit and OutForDelivery the same way, then call Shopper\Core\Actions\MarkShipmentDeliveredAction: it records Delivered and dispatches OrderShipmentDelivered.
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:
use Shopper\Core\Enum\OrderRefundStatus;
$order->refund()->create([
'reason' => 'Product damaged',
'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 column points to the original discount while it exists and becomes null when that discount is deleted. The four snapshot columns (discount_code, discount_type, discount_value_at_apply, discount_currency_code) keep the data even after the discount is edited or deleted. This follows the Shopify pattern of immutable order records.
The 2.x Order model has no discount relationship. Load the discount from its id:
use Shopper\Core\Models\Discount;
$discount = Discount::query()->find($order->discount_id);
$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 Shopper\Core\Models\Order;
$orders = Order::query()
->where('discount_id', $discount->id)
->get();Shopper runs the same query with ->where('customer_id', $customerId)->exists() to enforce the per-user usage limit.
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();Each item's total is unit_price_amount * quantity - discount_amount, without tax. The price_amount column is a different value: the total computed at checkout by CreateOrderFromCartAction, which adds tax when your prices exclude it. Orders you create yourself only get a price_amount if you set it.
Events
Shopper dispatches these events during the order lifecycle. OrderCreated, OrderDeleted and OrderItemCreated fire on every Eloquent create or delete, whatever code runs it. OrderShipped fires when the order's shipping_status becomes shipped, and OrderShipmentDelivered fires from MarkShipmentDeliveredAction. The others fire from the order detail page of the admin panel: updating status or payment_status in your own code dispatches nothing.
use Shopper\Core\Events\Orders\OrderCreated;
use Shopper\Core\Events\Orders\OrderItemCreated;
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' => shopper_currency(),
'channel_id' => $channelId,
'status' => OrderStatus::New,
]);Complete Order with Items and Addresses
Create the shipping and billing addresses, then the order and its items from the cart lines:
use Shopper\Core\Models\Order;
use Shopper\Core\Models\OrderAddress;
$shippingAddress = OrderAddress::query()->create([
'customer_id' => auth()->id(),
'first_name' => 'John',
'last_name' => 'Doe',
'street_address' => '123 Main St',
'city' => 'New York',
'state' => 'NY',
'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',
'state' => 'NY',
'postal_code' => '10001',
'country_name' => 'United States',
]);
$order = Order::query()->create([
'number' => generate_number(),
'customer_id' => auth()->id(),
'currency_code' => $cart->currency_code,
'shipping_address_id' => $shippingAddress->id,
'billing_address_id' => $billingAddress->id,
'shipping_option_id' => $carrierOptionId,
'zone_id' => $zoneId,
]);
foreach ($cart->lines as $line) {
$order->items()->create([
'name' => $line->purchasable->name,
'sku' => $line->purchasable->sku,
'quantity' => $line->quantity,
'unit_price_amount' => $line->unit_price_amount,
'product_id' => $line->purchasable_id,
'product_type' => $line->purchasable_type,
]);
}This example only copies the lines. To turn a cart into an order, use CreateOrderFromCartAction (see the Storefront Example): it also sets price_amount and tax_amount, reserves stock and the discount, and writes the tax lines.
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 ordersRetrieving Orders
To get all non-archived orders with their relationships:
use Shopper\Core\Enum\OrderStatus;
use Shopper\Core\Models\Order;
$orders = Order::query()
->notArchived()
->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 the next order number:
$orderNumber = generate_number();This returns a formatted string like ORD-20260327-001234. The format is configurable under the generator key of config/shopper/orders.php (config('shopper.orders.generator')):
| Key | Default | Description |
|---|---|---|
prefix | ORD | Text before the number, null to remove it |
separator | - | Character between each part |
date_format | Ymd | PHP date format of the date part, null to remove it |
start_sequence_from | 1 | Added to the id of the last order to get the sequence |
pad_length | 6 | Length of the sequence after padding |
pad_string | 0 | Character used for padding |
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 orderCreates 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()
{
$cart = Cart::current();
abort_if($cart === null, 404);
$order = resolve(CreateOrderFromCartAction::class)->execute($cart);
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, reserving the discount and the stock, writing the tax lines, and marking the cart as completed. It throws CartCompletedException when the cart was already converted, DiscountLimitReachedException when the discount has reached a usage limit, and InsufficientStockException when the stock cannot cover a line (all in Shopper\Cart\Exceptions). It does not set shipping_option_id, because the 2.x cart has no shipping option: set it on the order yourself. See the Cart page for details.
Order Status Flow
The order detail page of the admin panel offers these transitions:
| From Status | Possible Transitions |
|---|---|
| New | Processing, Cancelled, Archived |
| Processing | Completed, Cancelled, Archived |
| Completed | (terminal state) |
| Cancelled | Archived |
| Archived | (terminal state) |
Mark complete needs a paid order. Archive is offered only while the order is unpaid. Cancel Order follows canBeCancelled(). Mark as paid also moves a New order to Processing. Shipments change the status too: the first pickup moves a New order to Processing, and once every item is delivered, a Processing order moves to Completed. The model itself does not block any transition when you update status in your own code.
Last updated on
Edit on GitHub