Appearance
Shipments
Ship an order in one or more parcels with a carrier and a tracking number: the customer gets the tracking link by email and text and sees it on the order in their account, the units leave the warehouse, and the order completes when the last parcel goes.
kitloom/ · admins: kitloom/, kitloom/
Video lessons
Recorded in the Filament admin; the Nova admin works the same way.
Ship the shop's orders in one parcel or several, each with a carrier and a tracking number. The customer gets an email with the tracking link (and a text, when the site texts), sees every parcel on the order in their account, the units leave the warehouse when the parcel does, and the order completes when its last unit has left.
How shipping works
- Make a shipment from the order: the lines still to ship are listed with what each has left — its quantity, less what a refund gave back, less what other shipments carry. Take all of them or some (half the order now, the rest when it comes in), pick the carrier, type the tracking number. The carrier's tracking page is filled in from the number; type a link yourself only for a carrier without one. With Ship now on, the parcel leaves as you save; turned off, the shipment is kept as a draft: nothing has happened yet, and a draft can be changed or cancelled.
- Ship it. The shipment is shipped, dated now, and:
- the units leave stock — with kitloom/inventory, the order's delivery moves them out of the warehouse they were reserved in; what is not shipped stays reserved;
- the order gets a note: Shipment SHP-000120 shipped with UPS (1Z…): Mug × 2;
- the customer gets the email, in the language they ordered in: the lines in this parcel, the carrier, the tracking number and a Track your parcel button, the address it goes to. A document a module makes for this email (kitloom/invoices) is attached;
- the customer gets a text with the tracking link, when kitloom/text-messages is installed and Order shipped is switched on there;
- when it was the last unit of the order, the order goes to Completed (which sends the shop's own "Completed order" email) — unless the setting below keeps it in Processing.
- Delivered marks a parcel that reached the customer. Returned marks one that came back (refused, not collected): the owner is told, and its lines may be shipped again. The units are not put back on a shelf by this — receive them in the warehouse if they are to be sold again.
A pickup is an order collected at the counter: no carrier, no tracking. Shipping it hands it over — it is delivered at once, and the customer's email says they collected it.
Nothing is deleted: a draft is cancelled, a parcel that left is returned.
Screens
Shipments → Shipments. Every parcel with its order, status, carrier and tracking; filter by status and carrier. A shipment's page changes the tracking, ships a draft, marks it delivered or returned.
Shipments → Carriers. The common carriers — Canada Post, UPS, FedEx, DHL, USPS, Royal Mail, DPD, GLS, Nova Poshta, Ukrposhta — are added the first time the list is opened. Edit their names and order, hide the ones you never use, or add your own: a tracking page is an address with {number} where the tracking number goes (https://).
On the order's page, Ship opens the form above, and a Shipments button opens the list filtered to that order once it has any.
Shipments → Settings.
| Setting | What it does |
|---|---|
| Complete the order when everything has shipped | On (default): the last parcel moves the order to Completed. Off: it stays in Processing for you to complete. |
| Email the customer when a parcel ships | On (default): the shipment email goes to the billing address. The text has its own switch in Text messages. |
For the customer
The order's page in My account → Orders shows a Shipments block: each parcel that left with its number and date, the carrier and tracking number linked to the carrier's page — or Pickup. Drafts and cancelled shipments are not shown. Every shop theme draws the block (it comes as the order's extras.: a label and rows of label, value and link).
The text message
The kind is order.. The SMS reads “Shop: order #120 has shipped. Track it: https://…”. A WhatsApp template gets these variables, in order:
- the customer's first name
- the order number
- the carrier
- the tracking number
- the tracking link
- the shop's name
AI agents, notifications, webhooks, sheets, privacy
- AI agents (kitloom/ai), with
manage_:shipments shipments_(an order's shipments and what it still has to ship, or the latest by status),list shipments_(lines, carrier code, tracking number, pickup;create ship:ships at once),true shipments_(tracking,update ship,deliver,return,cancel),shipments_.carriers - Notifications (kitloom/notifications): Shipment returned (
shipment.), on by default.returned - Webhooks (kitloom/webhooks):
shipment.,shipped shipment., with the shipment and its lines.delivered - Sheets (kitloom/spreadsheets): the shipments out to CSV or Excel (
shipments:); nothing comes in from a file.shipment - Privacy (kitloom/privacy): Erase Personal Data blanks the tracking numbers of the orders the shop makes anonymous (WooCommerce → Accounts & Privacy: Remove personal data from orders on request). The shipments stay with their orders.
Permissions
manage_ — make, ship and change shipments and carriers. It goes to the roles that edit the shop's orders (edit_: the administrator, a shop manager). The order's note and its completion are written as that person when they may edit orders, else as the shop.
For developers
| What | Where |
|---|---|
| Tables | carriers, shipments, shipment_ (the site's table prefix in front); dates in UTC |
| Models | Kitloom\, Shipment, Shipment — registry keys carrier, shipment, shipment_ |
| Services | Kitloom\ (unshipped(), create(), update(), ship(), deliver(), mark, cancel()), Carriers |
| Events | Shipment, Shipment, Shipment (after the commit, with the actor) |
| The shop | stock through Kitloom\, the account block through Order, attachments through Order for the email id shipment_ |
| Configuration | config/ — ai, notifications, webhooks, sheets, privacy, filament, nova switches |
php
use Kitloom\Shipments\Shipments;
$shipments = app(Shipments::class);
$shipment = $shipments->create($order, $shipments->unshipped($order), ['carrier_id' => $ups->id, 'tracking_number' => '1Z999'], $user);
$shipments->ship($shipment, $user);The models can be replaced: Model in a provider of the application.
Tests
From the application that installs the package: php vendor/. The warehouse test runs with kitloom/inventory installed and is skipped without it.