Skip to content

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:

ModelPurpose
Shopper\Core\Models\OrderThe main order with statuses, totals, and foreign keys
Shopper\Core\Models\OrderItemProducts in the order with quantity, price, and fulfillment status
Shopper\Core\Models\OrderAddressBilling and shipping addresses snapshot
Shopper\Core\Models\OrderShippingShipments with carrier, tracking, and delivery dates
Shopper\Core\Models\OrderShippingEventTracking events for each shipment (location, status changes)
Shopper\Core\Models\OrderTaxLineTax breakdown per item or shipment
Shopper\Core\Models\OrderRefundRefund 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

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
numberstring(32)no-Order number
price_amountintegeryesnullOrder total in cents
tax_amountunsigned intyesnullTotal tax in cents
statusstring(32)no-Order status enum, set to new by the model
payment_statusstring(32)nopendingPayment status enum
shipping_statusstring(32)nounfulfilledShipping status enum
currency_codestringno-Currency code (USD, EUR, etc.)
notestextyesnullOrder notes
metadatajsonbyesnullCustom key/value data
parent_order_idbigintyesnullFK to parent order
payment_method_idbigintyesnullFK to payment method
channel_idbigintyesnullFK to channel
customer_idbigintyesnullFK to user
zone_idbigintyesnullFK to zone
billing_address_idbigintyesnullFK to order address
shipping_address_idbigintyesnullFK to order address
shipping_option_idbigintyesnullFK to carrier option
discount_idbigintyesnullFK to the discount that was redeemed (nullOnDelete)
discount_codestringyesnullSnapshot of the discount code at placement
discount_typestring(32)yesnullSnapshot of the discount type (percentage/fixed_amount)
discount_value_at_applyunsigned intyesnullSnapshot of the discount value (cents for fixed amount, raw for percentage)
discount_currency_codechar(3)yesnullCurrency the discount was applied in
cancelled_attimestampyesnullCancellation date
archived_attimestampyesnullArchive date
deleted_attimestampyesnullSoft delete timestamp
created_attimestampyesnullCreation timestamp
updated_attimestampyesnullLast update timestamp

OrderItem Table

ColumnTypeNullableDescription
idbigintnoPrimary key
namestringyesProduct name at time of purchase
skustringyesProduct SKU at time of purchase
quantityintegernoQuantity ordered
unit_price_amountintegernoUnit price in cents
tax_amountintegernoTax amount in cents
discount_amountintegernoDiscount amount in cents
product_idbigintnoPolymorphic relation ID
product_typestringnoPolymorphic relation type
order_idbigintnoFK to order
order_shipping_idbigintyesFK to order_shipping (shipment)
fulfillment_statusstringyesFulfillment status enum value

OrderAddress Table

ColumnTypeNullableDescription
idbigintnoPrimary key
customer_idbigintyesFK to user
first_namestringnoFirst name
last_namestringnoLast name
companystringyesCompany name
street_addressstringnoStreet address
street_address_plusstringyesAdditional address line
postal_codestringnoPostal/ZIP code
citystringnoCity
statestringyesState/province/region
phonestringyesPhone number
country_namestringyesCountry name

OrderShipping Table

ColumnTypeNullableDescription
idbigintnoPrimary key
statusstring(32)yesShipment status enum
shipped_atdatetimeyesShipment date
received_atdatetimeyesDelivery date
returned_atdatetimeyesReturn date
tracking_numberstringyesCarrier tracking number
tracking_urlstringyesTracking URL
voucherjsonyesShipping voucher data
order_idbigintnoFK to order
carrier_idbigintyesFK to carrier

OrderRefund Table

ColumnTypeNullableDescription
idbigintnoPrimary key
reasontextyesRefund reason
amountintegernoRefund amount in cents
statusstringnoRefund status enum
currencystringnoCurrency code
notestextyesAdmin notes
metadatajsonbyesCustom key/value data
order_idbigintnoFK to order
user_idbigintyesFK 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
StatusDatabase ValueColorDescription
NewnewinfoNewly placed order
ProcessingprocessingprimaryOrder is being prepared
CompletedcompletedtealOrder finished
CancelledcancelleddangerOrder cancelled
ArchivedarchivedgrayRemoved 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
StatusDatabase ValueColorDescription
PendingpendingwarningAwaiting payment
AuthorizedauthorizedinfoFunds held, not yet captured
PaidpaidsuccessFunds collected
Partially Refundedpartially_refundedorangeSome amount refunded
RefundedrefundedgrayFull amount refunded
VoidedvoideddangerCancelled 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
StatusDatabase ValueColorDescription
UnfulfilledunfulfilledwarningNo items shipped yet
Partially Shippedpartially_shippedinfoSome items shipped
ShippedshippedindigoAll items shipped
Partially Deliveredpartially_deliveredprimarySome packages delivered
DelivereddeliveredsuccessAll packages delivered
Partially Returnedpartially_returnedorangeSome items returned
ReturnedreturnedgrayAll 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 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
StatusDatabase ValueColorDescription
PendingpendingwarningAwaiting processing
Forwarded to Supplierforwarded_to_supplierinfoSent to external supplier (dropshipping)
ProcessingprocessingprimaryBeing prepared
ShippedshippedindigoIn transit
DelivereddeliveredsuccessReceived by customer
CancelledcancelleddangerFulfillment 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($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 orders

Retrieving 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')):

KeyDefaultDescription
prefixORDText before the number, null to remove it
separator-Character between each part
date_formatYmdPHP date format of the date part, null to remove it
start_sequence_from1Added to the id of the last order to get the sequence
pad_length6Length of the sequence after padding
pad_string0Character used for padding

Permissions

The admin panel generates five permissions for order management:

PermissionDescription
browse_ordersView the orders list
read_ordersView a single order detail
add_ordersCreate new orders
edit_ordersEdit existing orders
delete_ordersDelete 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()
    {
        $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 StatusPossible Transitions
NewProcessing, Cancelled, Archived
ProcessingCompleted, Cancelled, Archived
Completed(terminal state)
CancelledArchived
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