Order Management, Fulfillment, and Refunds in Site Store Pro

Admin Home Dashboard

Navigate to /admin/dashboard for a real-time overview of store performance.

KPI Cards

Four headline metrics appear at the top of the dashboard:

Total Sales Revenue

Aggregate revenue from all completed orders in the selected date window.

Orders Processed

Count of orders that have moved past the pending state.

Pending Orders

Active orders awaiting fulfillment action.

Active Customers

Unique customers who placed at least one order in the period.

Dashboard Widgets

Widget	Description
Order Activity & Revenue Trends	SVG line/bar graph of daily order volume and revenue
Orders vs Abandoned Carts	Conversion rate widget comparing completed orders to abandoned cart sessions
Cart Conversion Funnel	Step-by-step funnel from product view → add-to-cart → checkout → purchase
Customer Spend Analysis	Distribution of spend per customer segment
Product Sales Performance	Top-performing products by revenue and unit count

Date Filters

The dashboard defaults to the last 30 days. All KPI cards and widgets update when you change the range.

Available presets:

Filter	Window
30d	Last 30 days (default)
60d	Last 60 days
90d	Last 90 days
120d	Last 120 days
YTD	January 1 → today
Custom Range	Any start/end date you choose

Pending Orders Queue

GET /admin/pending-orders

Displays all active non-completed orders that require a fulfillment action. Results are paginated at 25 per page.

An order appears in the Pending Queue as long as its status has not been set to completed or cancelled. Use this view as your primary daily fulfillment worklist.

Orders List

GET /admin/ecommerce/orders

Full order lookup across all statuses. Paginated at 25 per page. Use the search bar to filter by order ID, customer name, or email.

Order Details

GET /admin/ecommerce/orders/{id}

The Order Details page is the central hub for invoice review, fulfillment, and refund actions.

Order Comments Block

Customer-submitted comments are rendered above the Items Purchased section on the invoice. No action is required — they display automatically if the customer entered a comment at checkout.

Payment History Log

A structured log of every payment event for the order:

Column	Description
Date	Timestamp of the payment event
Method	Payment gateway used (e.g. Stripe, PayPal)
Status	Outcome: Approved, Declined, Refunded, etc.
Authorization Code	Gateway-returned auth reference
Amount	Dollar value of the transaction

Mark Shipped

Clicking the Mark Shipped button immediately:

Updates the order status to Shipped (status 2).
Triggers and sends a shipment confirmation email to the customer.

The shipment confirmation email is sent the moment you click Mark Shipped. Confirm the shipping address and tracking details are correct before clicking.

You can also trigger the same action via the Status dropdown: selecting status value 2 (Shipped) has identical behavior — the confirmation email fires immediately.

Send Download Reminder

For orders containing digital items, the Send Download Reminder button manually re-dispatches the download reminder email to the customer on demand.

This button is only visible on orders that include at least one digital download item.

Double-Confirmation Action Gate

High-consequence email actions — Resend Order Confirmation and Send Download Reminder — require two clicks to execute:

The first click reveals a confirmation prompt inline on the page.
The second click sends the email.

This two-step gate prevents accidental duplicate emails. Do not click through both steps unless you intentionally want to re-send the email to the customer.

Order Status DB Value	Label	Notes
1	Open \| Pending	Default on order placement
7	Completed	No Email Sent
2	Shipped	Triggers shipment confirmation email
6	Back-Ordered	No Email Sent
8	Partially Refunded	No Email Sent
3	Refunded	No Email Sent
4	Cancelled	No Email Sent
0	Order Failed Or Awaiting Payment	n/a
10	Awaiting Payment By Check or PO	n/a

Partial or Full Refunds

Partial or full refunds are issued directly from the Order Details page (/admin/ecommerce/orders/{id}).

Open the Order

Navigate to Admin → Orders and click the order you need to refund.

Set Order Status (Optional for Full Refunds)

Change the order status using the Update Order Status dropdown to either Refunded or Partially Refunded and then click the Apply Status button (this will not send the customer an email automatically).

Note: If the entire order amount is refunded across payments, the order status will automatically update to Refunded upon processing the refund, allowing you to skip this manual status update.

Click the Refund Button in Payments List

Locate the Payments section and click the Refund button next to the specific payment you want to refund.

Automatic Gateway Dispatch: If the payment was processed via Stripe, PayPal, or Paddle, the refund will automatically post directly to the customer’s payment provider via their API.

Enter Refund Amount

In the refund modal, review the maximum refundable balance. The field defaults to the full remaining payment amount, but can be modified to any smaller amount for partial refunds. You may also add an optional administrative note or reason.

Confirm & Process Refund

Ensure the Post refund via Payment Processor API toggle is enabled (auto-checked for gateway transactions), and click Confirm & Process Refund. The gateway executes the credit, records the refund transaction in order_refunds, updates the payment status, and recalculates the balance due.

1. Direct Gateway API Linkages

When an admin processes a refund, the system resolves the associated payment method and interacts with the respective processor API:

1. Stripe Integration

Driver: App\Services\Payments\Processors\StripeProcessor
Mechanism: Calls the Stripe REST API via \Stripe\Refund::create().
Identifier Resolution:
- Automatically handles Payment Intent IDs (pi_...), Charge IDs (ch_...), or Customer Payment Methods (pm_...).
- If a Subscription agreement ID (sub_...) is provided, it retrieves the latest invoice and its underlying PaymentIntent to execute the refund.
Amount Handling: Converted to integer cents with currency preservation.

2. PayPal Integration

Driver: App\Services\Payments\Processors\PayPalProcessor
Mechanism: Calls the PayPal Captures API v2 (POST /v2/payments/captures/{capture_id}/refund).
Identifier & Subscription Fallback:
- Automatically resolves capture IDs from PayPal Checkout Order IDs or Subscription agreement IDs (I-...).
- If the transaction is a subscription billing agreement sale, it automatically falls back to PayPal’s Sale Refund API (POST /v1/payments/sale/{sale_id}/refund).
Error Diagnostics: Intercepts granular error issues and descriptions from PayPal API responses (e.g., already refunded, capture expired, or balance limits) and displays clear toast notifications.

3. Paddle Billing Integration

Driver: App\Services\Payments\Processors\PaddleProcessor
Mechanism: Calls the Paddle Billing Adjustments API (POST /adjustments).
Adjustment Types:
- Full Refund: Dispatches action: 'refund', type: 'full', and the transaction_id.
- Partial Refund: Retrieves the transaction line items and creates a partial line adjustment with type: 'partial' and item-level amount tracking.
Identifier Resolution: Resolves transaction IDs directly or via Subscription IDs (sub_...) and Customer IDs (ctm_...).

4. Test Gateway & Offline Ledgers

Test Driver: App\Services\Payments\Processors\TestProcessor returns simulated refund authorizations (TEST-RFND-XXXXXXXX) for testing environments.
Offline / Manual Override: Administrators can uncheck the Post refund via Payment Processor API toggle if the payment was already settled outside the gateway (e.g., cash, check, wire transfer, or direct bank chargeback resolution).

2. Payments Table & Status Behavior

The Payments table on the Order Details view provides clear real-time visibility into the lifecycle of each charge:

Status Badge	Condition	Description
Paid (Green)	`payment_status = 1`	Charge is captured with no refund balance deducted.
Partially Refunded (Amber)	`payment_status = 3` or `refunded_amount > 0`	A portion of the payment has been refunded. Displays the refunded amount subtext (e.g. `-$25.00 refunded`).
Refunded (Red)	`payment_status = 2` or `remaining_refundable = 0`	The payment has been 100% refunded. The Refund button is disabled with a checkmark.
Pending (Slate)	`payment_status = 0`	Payment authorization is incomplete or awaiting settlement.

Balance Summary Calculations

The order ledger dynamically reflects:

Order Total: Original total order charge.
Total Paid: Sum of all payments recorded in order_payments.
Total Refunded: Sum of all refunds recorded in order_refunds (displayed in red).
Balance Due: max(0, Order Total - Total Paid + Total Refunded). Displays a green Paid in Full badge when the net balance due is $0.00.

3. Automated Order Status & Inventory Safeguards

Automatic Order Status Elevation

When cumulative refunds equal or exceed the order’s total charge (order_total), the overall orders.order_status is automatically set to 3 (Refunded).
For partial refunds, administrators can optionally set the order status to Partially Refunded via the status dropdown.

Inventory Restocking Safeguard

When the first refund on an order is created, the system iterates over the order line items (order_details) and increments the available product stock (product_inventory.quantity_available += item_qty).
Subsequent partial refunds on the same order will not duplicate inventory restocks.

4. Code & Architecture Reference

Component	Path	Description
Refund Service	`app/Services/Payments/PaymentRefundService.php`	Centralized refund orchestrator managing validation, gateway API dispatch, and database transactions.
Contract	`app/Services/Payments/Contracts/PaymentProcessorInterface.php`	Defines the standard `refund(string $transactionId, float $amount, ?string $reason, string $currency)` contract.
Stripe Processor	`app/Services/Payments/Processors/StripeProcessor.php`	Stripe API refund implementation.
PayPal Processor	`app/Services/Payments/Processors/PayPalProcessor.php`	PayPal Captures v2 and Subscriptions v1 refund implementation.
Paddle Processor	`app/Services/Payments/Processors/PaddleProcessor.php`	Paddle Billing Adjustments API refund implementation.
Test Processor	`app/Services/Payments/Processors/TestProcessor.php`	Simulated sandbox test refund driver.
Order Payment Model	`app/Models/OrderPayment.php`	Includes `refunds()` relation, `refunded_amount`, and `remaining_refundable` accessors.
Order Refund Model	`app/Models/OrderRefund.php`	Includes `payment()` relation and `order_payment_id` attribute.
Admin Controller	`app/Livewire/AdminOrderDetails.php`	Livewire component managing modal state, validation, and refund execution.
Blade View	`resources/views/livewire/admin-order-details.blade.php`	Renders the Payments table, status badges, and interactive refund modal.
Toast Component	`resources/views/components/toast-alert.blade.php`	Renders real-time success and error alerts with secure HTML entity encoding.

Invoice Address Formatting

US and Canadian order invoices display the city, state, and ZIP in the standard inline format:

San Diego, CA 92101

City — customer’s city
State — two-letter abbreviation positioned between city and ZIP (US) or province abbreviation (CA)
ZIP / Postal Code — appended after the state abbreviation

Checkout Custom Fields Manager

GET /admin/ecommerce/checkout/processors

Access to the Checkout Custom Fields Manager is restricted to Admin role only.

Use this tool to inject custom data-collection fields directly into the checkout flow.

Field Positions

Position	Step	Placement
Checkout Step 1	Shipping form page	Rendered below the shipping address form
Billing Page Step 2	Payment page	Rendered above the payment card input

Field Types

Type	Renders As
`input`	Single-line text input
`textarea`	Multi-line text area
`select`	Dropdown `<select>`
`radio`	Radio button group
`checkbox`	Single checkbox
`checkbox_group`	Multiple-selection checkboxes

Billing Page User Type Filter

Step-2 fields can be targeted to specific customer segments:

Setting	Visibility
Both	Shown to all customers
Public Only	Shown only to standard (non-wholesale) customers
Wholesale Only	Shown only to wholesale accounts

Data Storage

All custom field responses are stored in the orders.custom_field_data JSON column on the order record. The data is available in the Order Details view and exportable via the Orders export.

Session Carryover

Step-1 (shipping page) field values are held in session after the customer advances. When the order is placed, Step-1 values are merged with Step-2 values and written together into orders.custom_field_data.

Session (Step 1 values)
        +
Form POST (Step 2 values)
        ↓
orders.custom_field_data  (single merged JSON object)

​Admin Home Dashboard

​KPI Cards

Total Sales Revenue

Orders Processed

Pending Orders

Active Customers

​Dashboard Widgets

​Date Filters

​Pending Orders Queue

​Orders List

​Order Details

​Order Comments Block

​Payment History Log

​Mark Shipped

​Send Download Reminder

​Double-Confirmation Action Gate

​Status Dropdown Reference

​Partial or Full Refunds

​1. Direct Gateway API Linkages

​1. Stripe Integration

​2. PayPal Integration

​3. Paddle Billing Integration

​4. Test Gateway & Offline Ledgers

​2. Payments Table & Status Behavior

​Balance Summary Calculations

​3. Automated Order Status & Inventory Safeguards

​Automatic Order Status Elevation

​Inventory Restocking Safeguard

​4. Code & Architecture Reference

​Invoice Address Formatting

​Checkout Custom Fields Manager

​Field Positions

​Field Types

​Billing Page User Type Filter

​Data Storage

​Session Carryover

Admin Home Dashboard

KPI Cards

Dashboard Widgets

Date Filters

Pending Orders Queue

Orders List

Order Details

Order Comments Block

Payment History Log

Mark Shipped

Send Download Reminder

Double-Confirmation Action Gate

Status Dropdown Reference

Partial or Full Refunds

1. Direct Gateway API Linkages

1. Stripe Integration

2. PayPal Integration

3. Paddle Billing Integration

4. Test Gateway & Offline Ledgers

2. Payments Table & Status Behavior

Balance Summary Calculations

3. Automated Order Status & Inventory Safeguards

Automatic Order Status Elevation

Inventory Restocking Safeguard

4. Code & Architecture Reference

Invoice Address Formatting

Checkout Custom Fields Manager

Field Positions

Field Types

Billing Page User Type Filter

Data Storage

Session Carryover