CartThrob Order Manager Version 9.0.1

Overview

CartThrob Order Manager is bundled with CartThrob 9 and provides control panel tools for:

• order management
• gateway actions (refund, capture, and void when supported by the payment gateway)
• tracking updates and resend-email workflows
• dashboard and report generation
• saved reports and CSV/XLSX export
• invoice/packing/custom template output

Requirements

• CartThrob 9.0.1
• PHP >= 7.4 (from cartthrob_order_manager/composer.json)
• ExpressionEngine version supported by CartThrob 9
• Orders channel configured in CartThrob (save_orders / orders_channel)

Installation

Bundled path:

/system/user/addons/cartthrob_order_manager/

If needed, install from ExpressionEngine control panel:

1. Go to Add-ons.
2. Install CartThrob Order Manager.
3. Confirm CartThrob itself is already installed.

Upgrading

1. Deploy updated CartThrob files.
2. Run add-on updates in the control panel.
3. Re-save Order Manager settings.
4. Validate gateway-specific actions (refund/capture/void) in staging.

Start Here (10-Minute Setup)

If you are new to Order Manager, focus on one outcome first: process one real order end-to-end from payment to fulfillment communication.

You should be able to complete these goals after setup:

• find and update orders quickly
• send shipping/tracking updates to customers
• run basic sales and customer reports
• export data for accounting, support, or fulfillment

Prerequisites Checklist

• CartThrob is installed and the orders channel is configured.
• You have at least one test or real order saved.
• The order channel includes these fields: order_tracking_number, order_shipping_note, and order_refund_id (recommended for refund bookkeeping).
• You know whether your payment gateway supports capture, void, and refund.
• Optional but recommended: set invoice_template and packing_slip_template in Order Manager Settings.

First Success Path

1. Open Orders and choose a recent order.
2. Confirm status and totals on the order detail page.
3. Add a tracking number and shipping note, then submit.
4. Resend the completed-order email to a test address.
5. Open Customer Report and export CSV once so your team can verify downstream format.

Common Tasks With Examples

1. Process a New Paid Order

Goal: move a paid order from review to fulfillment status.

1. Go to Orders.
2. Click the order ID to open detail.
3. Review transaction ID, totals, item lines, and shipping address.
4. If your workflow requires capture and the gateway supports it, use Capture Order.
5. Set the desired status (for example, processing to completed) and save.

Example: Order #1024 comes in as processing. After warehouse verification and capture, set status to completed.

2. Add Tracking and Notify the Customer

Goal: attach shipment data and keep customer communication consistent.

1. Open the order detail page.
2. In Tracking Info, set order_tracking_number (for example, 1Z999AA10123456784).
3. Set order_shipping_note (for example, Shipped via UPS Ground).
4. Choose the status to apply (for example, shipped).
5. Submit the form.
6. Use Resend Email if you need to manually resend customer confirmation.

If tracking/note fields are missing in the order channel, add them first or those values cannot be persisted.

3. Issue Full vs Partial Refund

Goal: choose the right refund operation and keep audit data clear.

1. Open order detail.
2. In Refunds, choose type: full refunds the entire order total; partial refunds only specified subtotal/tax/shipping amounts.
3. Submit and confirm result messages from the gateway.

Example partial refund: customer returns one item, refund subtotal=25.00, tax=2.00, shipping=0.00.

4. Run and Save a Reusable Order Report

Goal: build a report once, then re-run it in one click.

1. Go to Order Report.
2. Set criteria: status/date/total range, optional customer filters, and included totals/order fields.
3. Click Generate Report.
4. Enter report_title and click Save Report.
5. Next time, use the saved report dropdown and run/export directly.

Example: Weekly Completed Orders report filtered by status completed and last 7 days.

5. Analyze Product Performance

Goal: find top-selling products and drill into related orders.

1. Open Product Report.
2. Apply a date range.
3. Review totals and product rows.
4. Click the product detail link on a row title to open related order-level detail.
5. Export XLS or CSV for stakeholders.

6. Customer Follow-Up and Support Triage

Goal: quickly find high-value or frequent customers and view their order history.

1. Open Customer Report.
2. Sort/review total order amount and order count.
3. Click View orders for any customer to run a filtered order report.
4. Export CSV for support/account teams when needed.

Quick Links For Existing Users

• Need to update many order statuses quickly: see Orders List in the Control Panel Reference.
• Need per-order actions (capture/void/refund/tracking): see Order Detail.
• Need reusable filtered reports: see Order Report Criteria.
• Need exportable output of current criteria: see Report Result View.
• Need customer- or product-focused views: see Customer Report and Product Report.

Control Panel Reference

Dashboard (addons/settings/cartthrob_order_manager)

Forms

1. Report selector form:

- report: selects which dashboard report block is rendered below the chart - Refresh submit button: reloads the dashboard with the selected report

2. Date range form:

- date-range-select: preset ranges (last 30 days, last 3 months, last 6 months, last year) - date_start: custom start date for filtering dashboard totals/report output - date_finish: custom end date for filtering dashboard totals/report output - submit button: applies the selected or manual date range

Tables and Visuals

1. Order totals chart (Google Charts):

- stacked series: subtotal, tax, shipping - click behavior: - month bars open day-level totals - day bars open hour-level totals - order points can open individual order detail pages

2. If a report is selected, a report result table is rendered below the chart.

Settings (.../settings)

Form Fields

1. invoice_template:

- template selector used by the Print Invoice action in order detail

2. packing_slip_template:

- template selector used by the Print Packing Slip action in order detail

3. custom_templates grid:

- name: label used for each custom print/email template option - template: ExpressionEngine template to render for that custom template - behavior: - add new rows - reorder rows - remove rows

4. reports grid (custom report templates):

- name: label shown in report selectors - template: ExpressionEngine template used for that custom report - behavior: - add new rows - reorder rows - remove rows

Orders List (.../orders)

Form Fields

1. Bulk update form fields:

- status[entry_id]: per-row order status dropdown - selection[]: per-row checkbox used to choose which orders are updated - page: current pagination page (hidden, preserves the current page after update) - submit button Update Orders: applies selected statuses to checked rows only

Table Columns

• Order ID
• Date
• Customer Name
• Total
• Gateway
• Status (editable dropdown)
• Manage (toolbar actions)
• selection checkbox (for bulk update)

Click Behavior

• Order ID link opens order detail.
• customer name can link to a customer-filtered report when email is available.
• toolbar view opens order detail.
• toolbar remove opens delete confirmation.

Order Detail (.../order/{entry_id})

Primary Actions

• Print Invoice button (if invoice_template is configured)
• Print Packing Slip button (if packing_slip_template is configured)
• custom print buttons (if custom templates are configured)
• Delete This Order

Tables

1. Order summary table:

- transaction ID - payment method - subtotal, tax, shipping, total - delete-order action button row

2. Order items table columns:

- Item - Price - Subtotal - Quantity - Shipping - Weight - Entry ID - Taxable - Shippable

Click behavior: - item title links to the product entry edit page. - additional item metadata (including packaged items/options) is shown in detail rows under each item.

3. Address table:

- Billing Address - Shipping Address - behavior: - when the order is linked to a member, the billing side includes a member profile link

Forms

1. Capture form (only when gateway supports capture and order status is processing):

- id (hidden): order entry ID - total: amount to capture - submit: Capture Order

2. Void form (only when gateway supports void and order status is processing):

- id (hidden): order entry ID - submit: Void Order

3. Resend completed email form:

- id (hidden): order entry ID - return (hidden, value order): return target after submit - email_address: recipient override - email_subject: subject override - submit: sends the completed-order notification flow

4. Tracking form:

- id (hidden): order entry ID - order_tracking_number: tracking number to store on the order - order_shipping_note: shipment note saved with the order - status: status to apply as part of the tracking update - submit: saves tracking/note fields and can trigger status-change notifications - note: if tracking/note fields are not configured in the order channel, warnings are shown and those values cannot be stored

5. Refund form (only when gateway supports refunds):

- type: full or partial - full refund group fields: - total (display + hidden) - id (hidden) - partial refund group fields: - subtotal - tax - shipping - id (hidden) - submit - gateway extras: if the payment gateway provides additional refund fields, they are injected into the full/partial groups and submitted with the same form

6. Custom template email form (one per configured custom template):

- custom_template_id (hidden): identifies which configured custom template to use - return (hidden, value order): return target after submit - id (hidden): order entry ID - email_address: recipient override - email_subject: subject override - submit: sends the selected custom-template email

Order Report Criteria (.../order_report)

Forms

1. Saved report form:

- report: dropdown of saved reports - Remove? button opens remove-confirm modal for the selected report - submit runs the selected saved report - remove modal includes hidden content_id populated from the selected report

2. Report criteria form:

- where[status]: status filter (any or a specific order status) - where[date_start]: inclusive start date/time - where[date_finish]: inclusive end date/time - where[total_minimum]: minimum order total - where[total_maximum]: maximum order total - member/customer filters: - where[author_id] - where[email_address] - where[first_name] - where[last_name] - where[city] - where[state] - where[country_code] - included total checkboxes: show_fields[] (controls totals table rows) - included order field checkboxes: order_fields[field_key] (controls report columns) - submit actions: - Generate Report - Export XLS - Export CSV - save controls: - report_title: name used when saving a report - save_report: submit action to store the current criteria

Tables

• Included totals and included order fields are presented as checkbox tables.
• Saved report selector is shown as a dropdown table block.

Report Result View (.../run_report)

Tables

1. Totals table:

- rows are based on selected totals fields (show_fields[]).

2. Order result table:

- columns are dynamic based on selected order fields (order_fields[...]). - common columns include order id/title/date/status/totals and selected custom order fields.

Click Behavior

• entry_id and title open order detail.
• if order items are included, each item line links to product entry edit.

Form Fields

• hidden inputs preserve the applied report criteria (for example where[...], show_fields, order_fields, and report/customer/product filters).
• download buttons: download=xls / download=csv.
• report_title and save_report to save the current configuration.

Customer Report (.../customer_report)

Table Columns

• Name
• Email
• Phone
• Total Order Amount
• Total Orders
• Last Order
• action column (View orders)

Click Behavior

• member-linked customer names open member profile when available.
• email values render as mailto links.
• View orders opens an order report filtered by that customer email.

Form Fields

• download (hidden, default true)
• filename (hidden, default Customers)
• export buttons: download=xls / download=csv

Product Report (.../product_report)

Forms

1. Date filter form:

- where[date_start]: start date for purchased-item filtering - where[date_finish]: end date for purchased-item filtering - submit: applies the selected date range

2. Export/report action form:

- hidden carry-through fields for selected filters and optional id (single-product detail mode) - filename (hidden, value Products) - actions: - download=xls - download=csv - Generate Report

Table Columns

Columns are generated from purchased-item report data and typically include:

• product title
• entry id
• total sales
• price / price+tax
• shipping
• options/details

Click Behavior

• title includes a detail-report link for that product (order report filtered by product).
• entry id includes an edit-entry link.

Discount Report (.../discount_report)

Table Columns

• Discount ID
• Discount Type
• Discount Data
• Discount Used By
• action column exists in the table structure but is not populated in the current implementation

Form Fields

• download (hidden, default true)
• filename (hidden, currently Customers in code)
• export buttons: download=xls / download=csv

Delete Order (.../delete/{entry_id})

Form Fields

• confirm (yes/no)
• submit button (Delete Order) permanently deletes the order when confirm is yes

This action permanently removes order references from the database.

Notifications

Order Manager registers and uses:

• Cartthrob_order_manager_tracking_added_to_order notification event
• CartThrob completed notification path (used by resend-email flow)
• status-change notification path when status is changed through Order Manager actions

Optional Order Fields

For full feature support, configure these order-channel fields:

• order_tracking_number
• order_shipping_note
• order_refund_id

If tracking fields are missing, tracking values cannot be persisted to those order fields.

Changelog

Aligned to ct-code/CartThrob git history for system/user/addons/cartthrob_order_manager.

9.0.1 (2025-12-10)

• Version bump aligned with CartThrob 9.0.1.

9.0.0-b.3 (2025-02-21)

• Added PHP 8 deprecation guard (isset handling).
• Version bump to 9.0.0-b.3.

9.0.0-b.2 (2025-02-06)

• CartThrob 9 beta-line updates.

8.x Maintenance Highlights (2024)

• Order report UI and date-control improvements.
• Added grid-based order search field support.
• Removed older state/country dropdown filter approach.
• Fixed dashboard graph drilldown behavior.
• Fixed resend-email behavior in Order Manager.
• Fixed refund and void notification behavior.
• Fixed failed-refund URL and related URL/null-suffix issues.
• Added dynamic-property compatibility fixes.