Orders in the manager
Twenty-four grids live in the shop section: products, categories, variants, options and their values, prices, orders with their lines and history, payments, receipts, currencies, statuses, payment methods, delivery methods, promo codes, addresses, requisites, size charts, stock-alert subscriptions and cron runs.
Every entity has the PageBlocks field constructor on it, which is the part worth knowing before you ask for a feature: a field an administrator adds with the mouse lands in a JSON column by itself. No migration, no accessor, no release.
Order numbers
pbshop_order_number is a pattern — {year}/{seq:3} by default, giving 2026/001. Available: {year}, {yy}, {month}, {day}, and {seq} with as many leading zeros as you like.
The counter resets within whatever stands before {seq}. With the default that means every year; with {seq:5} alone it never resets.
Statuses
Statuses are yours to define — pb_shop_statuses, with a name, a colour, a sort order and three flags. Four ship in the seed: New, Paid, Shipped and Cancelled.
| Flag | What it means |
|---|---|
is_paid | grant access — the moment a subscription starts counting |
is_canceled | the order is closed: cancelled or returned |
notify | email the buyer when the order enters this status |
is_paid does not mean the money arrived
It is set on "Shipped" as well as "Paid" in the shipped seed, because it answers "should this buyer have access", not "is there money". The question about money is isSettled(), which looks at whether any payment row has a paid_at.
Build your own logic on the wrong one and it will look right for months: most orders are paid before they ship. It showed up as a real bug in cash on delivery — see Delivery.
The two flags are mutually exclusive: nothing will let you save a status that is both paid and cancelled. Until 2026-10-13 nothing stopped you — the seed simply only handed out sensible combinations.
The history feed
Every order carries an append-only feed: what happened, when, and who did it. Created, quick-ordered, paid, access revoked, extended, status changed, cash on delivery settled, refunded, receipt issued, waybill issued, order adopted.
The author is taken from the route, not from the session, and that distinction was a bug worth remembering: a guest purchase used to be signed by whichever administrator happened to have the manager open in another tab. Now a manager route is signed by the person in the manager session, a storefront route by the logged-in buyer, and a guest or a gateway callback by nobody.
A guest action and an automatic one are indistinguishable in the grid — both have an empty author. That is an accepted cost, not an oversight.
The order card
Besides the composition and the history, the card has tabs for Delivery (the address snapshot and the waybill buttons), Buyer (the account card — email and phone from the MODX profile, a link to it, the number of orders — plus the contact snapshot taken at checkout) and Payer (the legal-entity requisites).
Snapshots rather than live links, on purpose: contacts, address and requisites are copied onto the order when it is placed. A buyer who later edits their address book has not thereby changed where last month's parcel went.
Searching and filtering
Order search covers the number, the waybill, the promo code, the buyer's account and — through the JSON snapshots — contacts and requisites. A phone number is found both as written and as digits only.
The date filter offers ready-made spans (today, 7/30/90 days, a year) and two date fields which cancel each other out. It works on the creation date: an unpaid order has no paid_at and would fall out of every span. The upper bound is the end of the day, because "up to today" otherwise cuts off all of today.
Documents the shop draws itself
Three of them, all PDF, all rendered by the shop — not to be confused with a carrier's waybill, which is created at the carrier and printed on its form.
The invoice
For a legal entity, with the order's composition, delivery and discount. Downloaded from the order window; "Generate again" hands the new file straight back.
The seller is configured per currency on the bill payment method — an invoice in another currency is often issued by another legal entity, so seller is a map keyed by currency code with a default. Each entry holds name, reg_number, address, bank_name and bank_account.
pbshop_invoice_copy_email sends a copy to your bookkeeping as an attachment, both for one the buyer raised at checkout and one the manager assembled. One letter per new file, not per download.
The picking list
Select orders in the grid and print one sheet to walk the warehouse with.
The point of it is that it is grouped by item, not by order. A list of orders one after another is already on screen; carry that around and you walk back for the same t-shirt once per order it appears in. Here each line is named once with a total quantity, and the order numbers are listed beside it so the picked goods can be split up again.
A line is a variant, not a product: "Dress, 3" cannot be picked without the sizes. Rows are ordered by location in the warehouse, so the walk happens once instead of zig-zagging in SKU order; items with no location go last.
It reads the order snapshot, not the live variant — a variant may have been renamed or deleted since, and what gets picked is what was bought.
The packing slip
One page per order, to put in the box: the contents and the totals. It asks isSettled() rather than the status flag, precisely so a cash-on-delivery parcel does not go out with "paid" printed on it.
pbshop_shop_phone is the phone in its header. The shop name and site address come from site_name and the site URL, but MODX holds no phone number, and an email address is not a substitute: a box needs the channel that answers immediately.
All three take a site chunk instead of the built-in template — pbshop_picking_tpl, pbshop_packing_tpl and the invoice template — in the usual *_tpl forms: a chunk name, file: or @INLINE.
Two hundred orders per print
A deliberate ceiling: the PDF renderer holds the whole document in memory, and the honest limit is better than a blank page at order 400. Over the limit, the manager is told the number rather than being handed a truncated document.
Requisites and the address book
Both are "the buyer's saved cards", built on one mechanism, both snapshotted onto the order.
Requisites (pb_shop_requisites) hold the legal entity: name, registration number, VAT number, address, bank name, account, bank code, contact. The buyer manages them in the account, at /pay/requisites.
An invoice is not available to a guest at checkout
The cart page has no requisite fields — the form lives only in the account. So "Invoice" as a payment method works for a logged-in buyer with a card saved, and a guest cannot choose it.
The server side of this is finished: the question "does this method need requisites" is asked of the driver (needsRequisites()) in one place, so a second kind of invoice is possible. The missing half is the fields on the cart page.
Addresses (pb_shop_addresses) feed the "choose from the address book" picker and a "remember this address" checkbox at checkout.
Both manager grids are read and delete only. Not an omission: the address and the payer on a particular order are edited on that order, where the snapshot lives. Editing the buyer's saved card would not change the order, and a grid that looks editable but changes nothing is worse than one that does not.
Emails to the buyer
Three, sent by a listener on events rather than from the cart: money arrives by four different routes and the status is changed by a manager's form.
| Event | |
|---|---|
| Order placed | pbShopOrderCreate |
| Order paid | pbShopOrderPaid |
| Status changed | pbShopOrderStatus |
"Shipped" is not a template of its own — it is the status-change email, switched on by the notify checkbox on the status itself. In the seed that box is ticked for "Shipped" and "Cancelled".
Each template is overridable with a site chunk: pbshop_mail_order_created_tpl, pbshop_mail_order_paid_tpl, pbshop_mail_order_status_tpl. Strings exist in four languages. pbshop_order_mails switches all three off, for shops with their own mailing — the listener lives in the component, and the only other way to remove it would be editing bootstrap, which is a change lost on the next update.
Repeats are prevented by a list of what has already been sent, because pbShopOrderPaid fires on every edit of a paid order's row.
The mail layer itself sits on PageBlocks: a journal and a retry queue in pb_mails, the envelope template replaceable by a site chunk, attachments supported. pbshop_mail_from and pbshop_mail_from_name are empty by default — the site's own sender is used until the shop's letters need to differ from its registration letters.
Nothing emails the shop owner
There is no "new order" notification to you, and it is deliberately not a copy of the buyer's letter — it is a different document for a different reader. There is also no mail about an upcoming renewal or a failed charge; those are states rather than events and need the cron pass described in Subscriptions.
Until that exists: hang a listener on pbShopOrderCreate in core/App/config/pbshop.php and send whatever your shop wants.
What the manager cannot do
Said plainly so you can plan around it:
- no bulk status changes — printing is the only multi-select operation;
- no export of the order list (the catalogue does have CSV and XLSX — see Catalogue);
- no SMS or Telegram notifications;
- no per-section permissions — access is PageBlocks' permissions over the whole section, so a manager who can see orders can see everything;
- no partial-refund window — the service can refund part of an amount and the drivers support it, but there is no form to name the sum in.