Pricing data model
fulfillmenttools handles pricing data throughout the order lifecycle, but it doesn't make pricing decisions.
This article explains what pricing information fulfillmenttools accepts, how it stores pricing inputs, and how it derives deterministic order totals from those inputs.
You can fully reconstruct all order prices and intermediate totals at any time using only the pricing data stored with the order and the arithmetic-derived fields calculated by fulfillmenttools. Price reconstruction requires no catalog prices, defaults, or external systems.
The values calculated by fulfillmenttools, including derived fields, order totals, tax aggregates, and other calculated pricing values, are provided for operational fulfillment purposes only.
They are not intended and must not be used as an authoritative basis for invoicing, accounting, tax reporting, statutory reporting, or any other legally binding financial document.
You remain solely responsible for determining, validating, and maintaining legally compliant prices, taxes, invoices, accounting records, and financial reports using your own authoritative systems and processes.
Responsibility split
fulfillmenttools isn't a pricing engine. It doesn't make pricing decisions.
Pricing authority lies outside fulfillmenttools and typically resides in a customer‑owned pricing engine or an authorized user acting through a backoffice application or other administrative interface with permission to create or modify pricing data.
fulfillmenttools has exactly two responsibilities:
Store all pricing inputs verbatim
Calculate deterministic, arithmetic-derived values based on those inputs
fulfillmenttools never applies:
Business rules
Pricing logic
Tax logic
Decision‑making logic
Operational versus financial use
The pricing capabilities provided by fulfillmenttools are intended to support operational processes such as order management, fulfillment, picking, returns processing, operational reporting, and customer service workflows. The values calculated by fulfillmenttools are designed to provide consistent, traceable operational pricing information throughout the order lifecycle.
fulfillmenttools is not intended to serve as a financial, accounting, billing, invoicing, or tax system of record. Customers are responsible for maintaining and operating authoritative systems for financial reporting, invoice generation, accounting, tax determination, and statutory compliance.
Pricing scopes
Pricing data exists on two distinct scopes, which can coexist within the same order. These scopes are:
Line item pricing (item scope)
Order pricing (order scope)
The table below outlines the key differences.
Applies to
Single order line item
Entire order
Typical inputs
Base price
Line item discounts
Line item taxes (already calculated)
Line item surcharges
Order‑wide discounts (promotions, coupons)
Order‑wide fees
Aggregated tax information
Stored on
Article attribute level
Top-level pricing object
Core principles
Monetary representation
All monetary values are represented using:
value(integer)currency(ISO‑4217)decimalPlaces
Deterministic arithmetic
fulfillmenttools performs deterministic arithmetic aggregation using:
Multiplication
Addition
Subtraction
Division
No pricing logic
fulfillmenttools:
Doesn't apply pricing logic
Doesn't apply tax logic
Doesn't infer missing values
Representation normalization
fulfillmenttools doesn't perform business-rule rounding. However, some arithmetic operations (for example, percentage discounts or unit-price derivations) may produce results that can't be represented exactly using the integer-based monetary model (value + decimalPlaces). In such cases, fulfillmenttools applies deterministic normalization to the derived result so it can be represented using the required integer format.
For percentage-based discounts, normalization applies to the resulting subtotal after the discount is applied. The effective discount amount is then derived from the normalized subtotal.
This normalization is a technical representation constraint, not a pricing decision, and is applied consistently across all calculations.
Because normalization is applied to derived values rather than pricing inputs, small differences of one minor unit may occur compared to systems that apply normalization at a different calculation stage.
Such differences are expected because fulfillmenttools applies normalization to derived values rather than pricing inputs or intermediate calculation results. Systems that apply normalization at a different stage of the calculation may therefore produce slightly different results.
Customers are responsible for ensuring that downstream systems apply compatible calculation and normalization rules where consistency across systems is required. As a consequence of deterministic normalization, multiplying a normalized unit price by its quantity may result in a value that differs by up to one minor unit from the corresponding line-item total.
In such cases, the line-item total is considered the primary value for price aggregation and further calculations. The unit price represents a normalized derivation of that value.
Line item pricing inputs
Line item pricing inputs are provided as pricing-related attributes on the respective order line item.
The supported pricing categories are:
basePricediscounttaxsurcharge
For example:
Base price (input)
The base price represents the tax-inclusive unit price provided by the pricing authority.
fulfillmenttools treats base prices as authoritative input, stores them verbatim, and doesn't recalculate or infer missing values.
basePrice.value
Unit price including all taxes applicable to the item, before discounts
basePrice.currency
ISO currency
basePrice.decimalPlaces
Decimal precision
basePrice.valueOfMeasureForBasePrice
Reference quantity for base price
basePrice.unitKeyOfMeasureForBasePrice
Measurement unit for base price (must be the same unit key in quantity)
In the tabs below, you'll find examples of the difference between an item purchased by weight and by piece.
Line item discounts (input)
Line item discounts only apply to the specific item.
Possible representations:
Absolute discount amount
Percentage discount
Both
If both an absolute value and a percentage are provided, the absolute value is used for all fulfillmenttools‑calculated derived fields. Percentage values are treated as informational.
Line item taxes (input)
fulfillmenttools never calculates taxes.
Tax data is:
Provided by the pricing authority
Stored verbatim
Used for informational and reporting purposes only
All base prices are tax‑inclusive.
Tax values:
Aren't price‑forming
Aren't added on top of calculations
Line‑item surcharges (input)
All surcharge values must be pre‑calculated by the pricing authority. The surcharge applies to the entire line item, not per quantity.
Order pricing inputs
Order inputs are provided in the top‑level pricing object of the order entity.
For example:
Order discounts (input)
Apply to the entire order only.
Examples:
Campaign promotions
Vouchers
Coupons
Order discounts:
Don't affect individual line item prices
Aren't redistributed to items
Are treated as fixed inputs
If both a percentage and an absolute value are provided, the absolute value takes precedence.
Gift cards or prepaid instruments
This pricing model doesn't support gift cards, prepaid instruments, or store credit. Within this documentation, vouchers refer to discount codes that reduce the price of goods. Instruments carrying a monetary balance are not discounts. They are payment methods and don't reduce the value of the goods themselves. Such instruments may have their own redemption, balance management, and tax treatment rules, which are outside the scope of fulfillmenttools and aren't represented by this pricing model.
A voucher code may be carried through the order as an order-level discount by storing the code in tenantDiscountId and providing a discount value of 0. fulfillmenttools passes the code through without validation and doesn't derive any discount value from it.
External systems remain responsible for voucher redemption, remaining balance calculations, payment handling, and tax treatment.
Order fees (input)
Order fees apply once per order. They are treated as fixed order inputs. They aren't automatically recalculated or redistributed when you add, remove, or change line items.
Examples:
Packaging
Service fees
Handling fees
Order taxes (input)
Order taxes represent aggregated, informational tax summaries.
They can coexist with line item tax data.
fulfillmenttools:
Doesn't calculate taxes
Doesn't reconcile line item and order taxes
Doesn't validate tax consistency
Derived price components (fulfillmenttools‑calculated)
General rules
fulfillmenttools performs only deterministic arithmetic aggregation:
Multiplication
Addition
Subtraction
fulfillmenttools:
Doesn't apply pricing logic
Applies no tax logic
Performs no business-rule rounding. When derived values can't be represented exactly using the target integer representation (
value + decimalPlaces), fulfillmenttools applies deterministic normalization to the derived result.Infers no missing values
Derived fields: Line item
subtotalBeforeDiscounts
basePrice.value × quantity
or
basePrice.value × (quantity / valueOfMeasureForBasePrice)
Missing basePrice or quantity
null
subtotalAfterDiscounts
subtotalBeforeDiscounts − discount.value
Missing inputs
null
finalUnitPrice
subtotalAfterDiscount / quantity
Missing inputs
null
finalLineItemPrice
(finalUnitPrice × quantity) + surcharge.value
Missing inputs
null
If required inputs are missing, fulfillmenttools doesn't perform partial calculations and logs an internal warning.
Derived fields: Order totals
fulfillmenttools also calculates order totals based on:
Line item derived values
Order pricing inputs
Within the pricing object, you'll find the below fields within the total.priceBreakdown:
subTotal
Sum of all line item subtotalBeforeDiscounts
Any subtotal missing
null
totalDiscounts
Sum of all discounts affecting order total (item + order scope)
No discounts present
0
totalLineItemSurcharges
Sum of (surcharges.value)
No surcharge present
0
totalFees
Sum of order‑level fees
No fees present
0
totalTaxes
Sum of (tax.value (line-item)) + sum of (tax.value (order-level)) No VAT calculations in the totals. These are just for information.
Missing tax values
null
total
subTotal − totalDiscounts + totalFees + totalLineItemSurcharges
Any required input missing
null
Behavior when pricing is missing
If required pricing inputs for a derived field are missing, fulfillmenttools doesn't calculate that derived field, sets it to null, and logs an internal warning.
Derived pricing is calculated only when all required inputs are present. No partial derivations are performed.
Missing values are never interpreted as zero. You must explicitly provide a base price of 0 to indicate a free item. Derived values are only calculated when all inputs required for the respective calculation are present.
Price reconstruction guarantee
The final order price and all intermediate totals can be fully reconstructed using:
Stored pricing inputs
fulfillmenttools-calculated arithmetic derived fields
No catalog prices, defaults, assumptions, or external systems are required.
The reconstruction guarantee applies to price calculation and traceability. The pricing authority remains responsible for pricing correctness.
Contractual scope
This document describes the technical behavior of fulfillmenttools pricing functionality.
The contractual scope of fulfillmenttools responsibilities is defined exclusively by the applicable contractual agreements between fulfillmenttools and the customer.
This documentation doesn't constitute a contractual warranty, legal opinion, accounting guidance, tax guidance, or guarantee regarding the correctness, validity, or compliance of pricing, tax, accounting, or invoicing data.
Example
Last updated
Was this helpful?