Shipping Pricebook

Overview

The Shipping Pricebook applet is where an e-commerce or logistics administrator defines conditional shipping charges: a Shipping Pricebook is a named container, and each Shipping Priceset inside it says who qualifies (entity type, member class, member label, company, branch, delivery region, date range), which items in the cart it looks at (items, categories, code or name patterns, with minimum quantity, minimum amount and weight bands) and what is charged (a Standard Shipping Fee, a Handling Fee and a Fuel Surcharge, each with a price source, an operator and a value).

The applet only maintains this master data. The rules are applied by one consumer: the CP Commerce storefront. At checkout the shopper picks a shipping price book as the Shipping method, the storefront evaluates its price sets in the browser and writes the resulting fee as a line for the website’s shipping-fee service item on the shopping cart. Nothing in the ERP back office (POS, sales documents, the Java backend) evaluates shipping price books.

Where it fits

Screens and menus

The applet has two menu entries, Shipping Pricebook and Shipping Priceset, plus Settings and Personalization.

There are two editors for a price set. The Shipping Priceset menu opens priceset-edit; the Pricing Set tab of a Shipping Pricebook opens the nested pricebook-edit-priceset. Unlike the Pricebook applet, both offer the same rule types and the same three treatments and save the same bl_fi_mst_shipping_price_book_line row.

Configuration

Before you can use it

• A website with the shipping-fee process switched on in CP Commerce Admin → Website Edit → Details: tick Enable Shipping Fee Process, choose Shipping Fee Options = Shipping Pricebook, pick the Default Shipping Price Book Code and the Item Code for Shipping Fee. Without the item the storefront computes no line (the fee shows as RM 0.00); without the option the storefront runs the delivery-charge path instead (see Settings in other applets).
• A SERVICE item for the fee in Doc Item Maintenance (txn_type SERVICE). Its GL and tax settings decide how the fee posts once the cart becomes a sales order.
• Items and categories exist in Doc Item Maintenance for item / category rules; pricing schemes exist if a treatment uses Price Source = Pricing Scheme (the Treatment tab lists the schemes of the PRICING_SCHEME_ITEM list).
• Companies and branches exist in Organization for Company / Branch rules; member classes and labels exist in Membership Admin for the member rules.
• Delivery regions with a State value for Delivery Region rules — the storefront matches the shopper’s shipping-address state against the region’s State (see Lifecycle).
• Tenant permissions. Every applet endpoint checks API_TNT_DM_ERP_SHIPPING_PRICE_BOOK_OWNER / ADMIN or the matching CREATE / UPDATE / DELETE / READ code (TntErpPermissions L371-383; ShippingPriceBookPackageController L56-215). The storefront does not need any of them: it reads through shipping-pricebooks/website-ep/{websiteHdrGuid}/query, an anonymous tenant endpoint that only validates the website guid (controller L219-245).

Applet settings

Settings are applet-local in layout only: app.routing.ts routes settings/field-settings and settings/default-selection to the applet’s own components, and the shared FieldConfigurationComponent in blg-shared-utilities is not routed (gates.py has no controls for ShippingPricebookApplet). None of the applet’s own screens is functional:

• Field Settings is a static template — eight slide toggles (Lines Settings: Unit Discount, SST/VAT/GST, WHT, Blanket Order; Department Settings: Segment, G/L Dimension, Profit Center, Project) with no form binding, a SAVE button with no click handler and a component class with no logic (field-configuration.component.html, .ts). They are rendered but neither declared, persisted nor consumed.
• Default Selection renders Default Branch and Default Location. The component writes each change into this.appletContainer.bl_applet_exts, but appletContainer is never assigned (there is no subscription to appletSettings$, and the routed host <app-settings> neither binds that input nor listens to save; the shared SettingsComponent.onSaveDefault is commented out). Changing a value throws in the browser console and nothing is saved; no code in the applet reads DEFAULT_BRANCH or DEFAULT_LOCATION.
• Personalization → Default Selection has the same defect (personal-default-settings.component.ts L31-38 commented out).

No exposed, working control found (routes and settings components checked at commit 7894b78, 2026-09-02).

Settings in other applets that control this applet

Feature visibility / permissions

No client-side permission definitions are seeded for this applet (bl_applet_client_side_perm_dfn has no rows for ShippingPricebookApplet, checked 2026-09-05), so the Feature Visibility screen and the role / team / user permission listings under Settings have nothing applet-specific to gate. Access is decided by the tenant permissions listed under Before you can use it; the API returns not authorised when none of them is assigned.

Fields

Code and name inputs on the create forms accept letters, digits, space, hyphen and underscore only (blockSpecialChar), are upper-cased and trimmed on save, and are limited to 255 characters.

Shipping Pricebook — create

Shipping Pricebook — edit › Details

Shipping Priceset — create

Creating a price set appends a line to the book with three empty rule groups (hdr_doc_filter, multi_line_doc_filter, single_line_doc_filter, each top_level_logic = AND, negation_logic = FALSE, rules = []) and an empty treatment_json.treatment array, and PUTs the whole book.

Shipping Priceset — Rules tabs

Each Rules tab has Rules Logic (And / Or → top_level_logic) and Negation Logic (Enabled / Disabled → negation_logic) for the whole group, a grid of Rule Name · Rule Type, and a + that opens Add Rule. Every rule form has a required Rule Name and its own Negation Logic. Rules are saved immediately by the rule form (a PUT of the book), independently of the SAVE button of the price set.

Shipping Priceset — Treatment tab

Three independent blocks, each enabled by its checkbox: Standard Shipping Fee (STANDARD_SHIPPING_FEE), Handling Fee (HANDLING_FEE) and Fuel Surcharge (FUEL_SURCHARGE). Unticking a block removes its entry from treatment_json.treatment on save.

Lifecycle and effects

What the applet writes. Every action is a full PUT of the price book container (shipping-pricebooks, ShippingPriceBookService.put): header, extensions and lines together. Price set Delete does not remove the line; it sets status and property_json.status to DELETED and PUTs. Price book Delete calls DELETE /{guid} and the backend soft-deletes header, extensions and lines. Update, delete and price set actions also POST an audit row to shipping-pricebooks/events (bl_fi_mst_shipping_price_book_event, txn_type SYS_APPLET, actions PRICE_BOOK_UPDATED, PRICE_BOOK_DELETED, PRICING_SET_CREATED, PRICE_SET_UPDATED, PRICE_SET_DELETED); the create effect builds its PRICE_BOOK_CREATED event inside an inner pipe that is never subscribed, so that event is never written.

Backend validation. ShippingPriceBookPackageService.create/update run ShippingPriceBookDataConsistencyObject: header guid present and (on create) not already existing, revision and status present, every extension and line with a guid, hdr_guid equal to the header guid, revision and status. Failures come back as Core2DataConsistencyException with codes such as SHIPPING_PRICEBOOK_HDR_OBJECT_GUID_ALREADY_EXISTS or SHIPPING_PRICEBOOK_LINE_OBJECT_HDR_GUID_DIFFERENT_FROM_PRICEBOOK_HDR_OBJECT_GUID. Nothing validates the rule or treatment JSON and nothing checks code uniqueness. The bl_fi_mst_shipping_price_book_rule_* tables, DCOs and controllers exist in the backend but no applet, storefront or admin code references them.

No posting. A shipping price book is master data: no server document type, no signums, no journal, no stock processor. The fee reaches the ledger only as an ordinary service-item line on the sales order the cart converts into, and posts by that item’s GL and tax configuration.

How the storefront applies it (the only consumer). All of this runs in the shopper’s browser (wavelet-cp-commerce, commit 247243251, 2026-09-03):

1. Load. loadShippingPricebookInit$ calls the anonymous website endpoint asking for header status ACTIVE, ordered by created date. The applet’s Status field is the extension PRICE_BOOK_STATUS, which the storefront never reads, so an Inactive price book is still loaded and offered; only a deleted one disappears.
2. Choose. The Shipping method block at checkout lists every loaded price book by name and icon (plus PICK UP IN STORE when enabled) with the website default pre-selected; selectActivePricebook = the shopper’s choice, else the website default.
3. Qualify. ShippingManager sorts the book’s price sets by priority_line ascending (missing → last; ties keep API order), drops DELETED ones — Inactive price sets are still evaluated — and keeps those whose Doc Hdr rules and Multi Line rules both pass. The Single Line tab is never evaluated. Within a group, Rules Logic And / Or and Negation Logic are honoured.
4. Select. selectPricesetBasedOnCalculationLogic always returns the first qualifying set. Calculation Logic on the book (FIRST_MATCH) is read but every value behaves as Sequential Match.
5. Compute. Aggregate = Σ over all cart lines of the Standard Shipping Fee price source (qty_base → quantity_base, amount_std, amount_net, amount_txn, price_unit_cost → unit_price_std). Each ticked treatment applies its operator to that same aggregate: MULTIPLY = aggregate × value, ABSOLUTE = value, ADD = aggregate + value, SUBTRACT = aggregate − value; an unticked treatment contributes 0. Fee = Standard + Handling + Fuel, rounded to two decimals. The Handling Fee and Fuel Surcharge blocks’ own Price Source is not used; Pricing Scheme as a price source reads a field that is not on the cart line and yields no usable number.
6. Write. The fee becomes a quantity-1 line for the website’s shipping-fee item (addShippingDocLine; the previous shipping line is marked DELETED), the cart revision is checked, and the coupon engine is re-run so a free-shipping voucher can discount the line.

Rule coverage at checkout.

Related applets

• Pricebook — the discount / sales-price / points sibling with the same rule and treatment design; its consumers (POS, sales documents, OCR) never read shipping price books.
• CP Commerce Admin — owns the website switches that decide whether, with which price book and against which item the storefront charges shipping.
• Shopping Cart — the fee is a line of the DRAFT cart; the coupon engine may discount it.
• Doc Item Maintenance — the shipping-fee SERVICE item, the items and categories in line rules, the pricing schemes offered in the Treatment tab, and the weight / dimensions used by weight bands.
• Organization — companies and branches for Company / Branch rules.
• Membership Admin — member classes and labels for member rules.
• Customer Maintenance — entity types for Entity Type rules.
• Sales Order — receives the fee as a service line when the cart converts.

Troubleshooting

Related documentation

• CP Commerce Admin — website Shipping Fee Options, default shipping price book, shipping-fee item and shipping providers.
• Pricebook — discounts, sales prices and membership points with the same rule engine design.
• E-Commerce module and Core module.