Carriers

Stockly → Operations → Shipping → Carriers lists every carrier the installation knows, from two sources that share one registry:

• Module — a shipping module announced it. Behaviour, possibly automatic booking; read-only here, because it is changed in that module.
• Own entry — a row created on this page: the carrier’s tariff (limits, services, weight brackets) with no module behind it. This is the form used for every carrier that goods are shipped with but that has no integration, which is most of them.

Columns: Carrier, Source, Default max weight, Max parcels, Requires, Books shipments, Rules using it.

The limits shown are that carrier’s defaults. A packaging rule may override every one of them.

Adding and editing a carrier of the shop’s own

Add carrier asks for the general facts first. As in the product form, the parts that depend on a saved row unlock after the first save, as tabs on the carrier’s own page. In the list, the name of an own entry opens the carrier’s page.

The page opens read-only, displaying the values rather than a form. Edit in the header switches the current tab to editing; Save writes the whole carrier, Cancel discards the draft. Tab titles carry the row counts, e.g. Services (3).

General — identity and limits:

• Technical name — the handle packaging rules store (lowercase letters, digits, -, _). Locked after the first save: renaming it would silently orphan every rule pointing at it.
• Limits — max weight per parcel, max parcels per shipment, max length and girth. Empty = no limit.
• Volumetric divisor — cm³/kg for the volumetric weight; 5000 for most European parcel networks. Empty = this carrier does not bill by volume.

Services — the carrier’s products (e.g. paket, kleinpaket, sperrgut), offered to the packer per parcel on the packing screen. The first one is preselected; the arrows set the order.

Weight brackets — the carrier’s price breaks as ranges: each row says “up to X kg”, the last row is open (∞). A bracket bound to a service applies to that service only. Prices are optional: a bracket without a price still describes where the tariff steps, and that is enough for advice. The parcel planner warns when a box sits just above a break (“Parcel 2: 20.4 kg — 0.4 kg above the 20 kg price break”) and when one more box would put every parcel under it. The advice is textual only; the split itself never changes, because without prices a split presented as better would be a guess. A packaging rule with a lower max weight trims the breaks above it out of the advice.

Surcharges — what the carrier adds on top of the base price. One charge is one technical name; rows sharing that name are its brackets, each stating an upper bound on one axis, either parcel weight or order value, together with the amount that applies inside it. Leave both bounds empty for an unconditional charge. Per row:

• Type — a fixed amount, a percentage of the base price, or a percentage of the order value.
• Charged — once per parcel (fuel, energy fees) or once per order (COD, insurance).
• Condition — always, or only on cash-on-delivery orders.

Real tariffs are already structured this way. A fuel surcharge that changes with weight is three rows named fuel: 33.9 % up to 20 kg, 39.7 % up to 31.5 kg, 42.2 % open. Insurance staggered by order value is rows named insurance with value bounds. When the fuel percentage changes next month, one number is changed rather than the whole price matrix.

A worked example, DHL Paket for a German shop: max weight 31.5, max length 120, girth 360, divisor 5000, services paket / kleinpaket / sperrgut, brackets up to 10, up to 20, open.

The shipping estimate

With prices in the weight brackets, the parcel panel shows what the current draft would cost: a figure per box and a net total in the summary line, recalculated as weights are entered and items moved. Hovering over the total shows the breakdown: the base price plus every surcharge by name.

The estimate is the shop’s own tariff applied and nothing more: net figures in the currency they were entered in, no VAT, no conversion. Where the tariff has no answer, the panel displays tariff incomplete rather than estimating: a box heavier than every priced bracket, or a value-based charge on an order the panel cannot price. Prices are optional throughout: a carrier without them shows no estimate, and everything else keeps working.

Outside systems can ask the same question over the API: POST /api/_action/p2lab-stockly/shipping/rates/quote with orderId and the drafted parcels (weightKg, service) returns the priced breakdown.

When a module and a row share a name

The module wins, deliberately. That is the upgrade path: a row called dhl is created first, a DHL module is installed a year later, and every packaging rule keeps working, because the module answers for the name from then on. The edit form warns when a row is shadowed.

The two columns that decide how much work an order needs

Requires — what the carrier insists on knowing:

• weight per parcel — the item-assignment screen opens instead of an evenly divided estimate. An estimate is usually accepted, but where overweight surcharges apply it costs real money.
• contents declaration
• nothing beyond a parcel count

Books shipments — whether the module can be asked for shipments automatically. Where it says No, the parcel still exists and still prints; the tracking code arrives by hand or from an outside system. An own entry always says No, because it is a tariff, not an integration.

A deleted row, an uninstalled module

A rule pointing at a carrier that no longer exists, whether a deleted row or an uninstalled module, keeps working. It falls back to the generic carrier: no limits, no objections. An uninstall elsewhere should not break shipping here; the delete dialog states how many rules will be affected before the deletion is confirmed. An inactive row behaves the same way as a deleted one until it is switched back on.