Ctrlk
API documentationIncident managementFeedback
Edit

Transport cost calculation logic

Transport costs represent the expenses incurred when goods are shipped between facilities or from a facility to the end consumer. These costs typically depend on the shipping service provider, the parcel or packaging type used, the destination country, and, depending on the chosen logic, additional factors such as weight or volume.

Packing logic and shipping cost calculation

fulfillmenttools applies bin-packing logic to determine how ordered items are distributed across available packaging units and calculates shipping costs accordingly.

Two effort levels are available:

The logic applied to a given transfer within a sourcing path is determined by how the packagingUnitByContexts object is configured in the respective facility connection.

If a packaging unit is referenced within a facility connection, the packagingUnitsByContexts property may only define the corresponding transit times. All other information is inherited from the referenced packagingUnit and must not be redefined at the facility connection level.

For details on how a fulfillment network is defined by facility connections and how they are structured, see the Facility connection article.

Determining which logic applies

The active logic for a given transfer is determined only by how packagingUnitByContexts is configured in the corresponding facility connection:

Configuration
Applied logic
Example

Packaging unit data is defined inline in packagingUnitByContexts in the facility connection.

Standard

The facility connection packagingUnitByContexts references an external packagingUnit

Advanced

Mixed logic within a sourcing route

The standard and advanced logics aren't mutually exclusive. Within a single sourcing route, different transfers can each apply a different logic, depending on how the respective facility connection is configured.

Standard logic

The use of the standard logic is well‑suited for scenarios in which the carrier portfolio within the network is relatively homogeneous, and the pricing structure is simple, with only marginal differences between carriers.

The standard packing logic applies when packaging unit information is defined directly within the facility connection object in packagingUnitByContexts. No reference to an external collection is required.

A first-fit decreasing algorithm is applied to assign items to packaging units. This approach offers sufficient accuracy across a wide range of use cases and improves calculation speed.

First-fit decreasing algorithm

  • Check whether the largest item fits within the highest priority packaging unit (usually the smallest and cheapest to ship), based on the item's dimensions and the package's dimensions.

  • If it does not fit, the next packaging unit is tried (in order of priority). If it fits, check for the next item to fit in this package, and so on.

  • Do this for every item. If a packaging unit is full (considering its dimensions and restrictions), check for a second package, starting again with the package of highest priority.

  • A packaging unit is full when the sum of the item volumes exceeds the inner parcel volume. However, an empty space (volumeBufferInPercent) might be deducted to ensure that the items really fit. Note: Geometries aren't considered, and no "Tetris" is played. So, it's important to leave some empty space.

  • A parcel is also full if the maximum item amount is reached. This feature ensures that only one item is placed in a single package.

Shipping costs are calculated using a standardized formula applied uniformly across all transfers using the standard logic.

Advanced logic

The advanced logic is particularly suitable in scenarios where the carrier portfolio is broad and includes multiple shipping methods (for example, parcel, pallet, bulky goods, and two‑person handling).

In such environments, an optimized packing strategy combined with price‑optimized routing can significantly reduce fulfillment costs. This approach is especially beneficial when at least one of the following conditions applies:

  • The network uses different parcel types

  • Items vary significantly in size or dimensional characteristics

  • The cost structure requires precise optimization across heterogeneous carriers

It should also be noted that the advanced logic is computationally more expensive and may not be ideal for very large networks where performance constraints are critical.

The advanced packing logic applies when packagingUnitByContexts within the facility connection references packaging units defined in a separate collection, rather than containing the packaging unit information inline.

Advanced algorithm

  • Finds the cheapest combination of packaging units: fulfillmenttools evaluates all feasible ways to group the ordered items into packaging units and selects the option with the lowest total cost.

  • Considers all available shipping options: From standard parcels to freight and pallet shipments, fulfillmenttools automatically picks the best packaging unit type for each part of your order.

  • Respects physical constraints: Item dimensions, weight limits, and carrier requirements are all factored in to ensure your shipment is valid and deliverable.

  • Guaranteed lowest shipping cost: The result will always be the optimized packaging solution, not just a "good enough" estimate.

In contrast to the first-fit decreasing approach, the advanced logic evaluates all possible distribution combinations within the solution space. The goal is cost optimization: the algorithm identifies the distribution of items across available facilities and their respective packaging units that results in the lowest overall shipping cost.

Packaging units defined in the separate collection also support a significantly broader set of configurable properties, including:

  • Girth measurement

  • Volumetric weight

  • Detailed price tables dependent on weight and destination region

Packaging unit type-specific definitions and calculation logics

The following section describes the logic applied to each packagingUnit type. It outlines the available configuration options, including the attributes and restrictions that can be defined for each type.

Also, it explains the factors used for price calculation, which are provided through the packagingPricingDetails associated with each packaging unit. Different shipping methods need different pricing calculation logics. These logics are defined per packagingUnit type and must be maintained accordingly.

All items are, by default, eligible for all packaging types unless this is explicitly restricted through packagingUnitsByContexts.context[] in the facility connection.

All the following examples are using advanced logic. So, using the packaging units endpoint.

Parcel

Definitions and restrictions

The parcel packagingUnit type can be used for standard parcel shipment, fully enclosed in a box. Three-dimensional constraints apply because carriers calculate costs and enforce size limits based on weight, height, length, and width.

The maximum permissible dimensions are defined through the mandatory fields maxWeight, maxHeightInMillimeters, maxWidthInMillimeters, and maxLengthInMillimeters. These values establish the physical limits for routing and packing decisions. If an article or article combination exceeds any of these dimensions, fulfillmenttools doesn't assign it to this packaging unit.

The optional volumeBufferInPercent allows configuring additional free space within the parcel to account for packaging materials or irregular article geometries.

The optional maxItemQuantity specifies the maximum number of items that may be placed in a single parcel. This configuration can be used for operational requirements such as handling hazardous goods or specialized packaging scenarios, including bottle shipments or flower logistics. Pricing structure and calculation logic

The shipping cost for a parcel unit is determined by the packagingPricingDetails configuration and is composed of up to three components.

The primary cost is derived from the pricing array, which defines weight-based price brackets. Each bracket specifies an upperThreshold in grams and the corresponding shipping price. The bracket whose upperThreshold is equal to or greater than the actual shipment weight applies. Two approaches are available for handling shipments that exceed all defined thresholds:

  • The highest configured upperThreshold matches the packaging unit's maxWeight exactly, ensuring no shipment exceeds the defined brackets.

  • An overflowFactor is defined, which specifies the additional cost per gram above the highest upperThreshold.

This approach allows pricing to extend beyond the last bracket without requiring an exhaustive weight table.

Optionally, price brackets can be differentiated by destination region using the zone field within each pricing object. A zone is defined by the ISO 3166-2 country code, followed by a dash and the first digits of the destination postal code (for example, DE-50 for Cologne, Germany). This allows different prices to apply based on the delivery location. This is particularly relevant for freight and pallet shipments, where regional pricing is standard practice among carriers, but it also applies to parcel shipments.

In addition, one or more surcharges can be configured in surchargesPerPackagingUnits and added to the net shipping price. Two surcharge types are supported:

  • ABSOLUTE_SURCHARGE_TYPE adds a fixed monetary amount per unit. Typical examples include a fixed handling fee for manual processing or special workflow steps, or a fixed fuel surcharge per shipment where the carrier does not apply percentage-based rates.

  • RELATIVE_SURCHARGE_TYPE adds a percentage of the net freight price. Typical examples include a percentage-based fuel surcharge or an environmental levy.

Example parcel cost calculation

Use the tabs below to click through the example scenario.

We'll set the following definitions:

  • Maximum dimension:

    • Maximum length: 120 cm

    • Maximum width: 60 cm

    • Maximum height: 60 cm

  • Maximum weight: 31.5 kg

  • Volume buffer: 5% (for packaging material)

Pallet

Definitions and restrictions

This packaging unit type can be used for pallet-based shipment for heavier or bulk freight. In addition to three-dimensional constraints, a volumetricWeightFactor is required because freight carriers charge based on whichever is greater — actual weight or volumetric (dimensional) weight. The factor converts physical volume into a comparable weight value for cost calculation.

fulfillmenttools calculates the volumetric weight by dividing the packaging units' volume by the carrier‑specific volumetricWeightFactor (very common: 5000 or 6000). Routing and cost calculation use this value whenever the volumetric weight exceeds the actual weight, ensuring that carrier constraints and billing rules are applied consistently.

volumetricWeight=(length⋅width⋅height)volumetricWeightFactorvolumetric Weight = \frac{(length ⋅width⋅ height)}{volumetricWeightFactor}

Additionally, a pallet may optionally define maxItemQuantity and volumeBufferInPercent, which are evaluated in the same way as for the parcel configuration.

Pricing structure and calculation logic

The shipping cost for a pallet unit follows the same zone-matching, weight-bracket, and surcharge logic as parcel units, with one additional step. Before the applicable price bracket is determined, fulfillmenttools calculates the shipment's volumetric weight using the mandatory volumetricWeightFactor. The greater of the actual weight and the volumetric weight is then used to select the price bracket. This reflects standard freight carrier practice, in which oversized but lightweight shipments are billed based on their dimensional weight rather than their actual weight. Multi-currency pricing, the overflowFactor, and surchargesPerPackagingUnits apply in the same way as for parcel units.

Example pallet cost calculation

Use the tabs below to click through the example scenario.

We'll set the following definitions:

  • Maximum dimension:

    • Maximum length: 120 cm

    • Maximum width: 80 cm

    • Maximum height: 180 cm

  • Maximum weight: 2000 kg

  • Volume buffer: 5% (for packaging material)

Bulky goods

Definitions and restrictions

This packaging unit type can be used for oversized or irregularly shaped items (for example, doors, bicycles, car tires, and so on) that can't be packed using a standard three‑dimensional box. Instead of height, length, and width, carriers for bulky goods typically apply girth‑based constraints, which express the combined circumference and longest dimension of a shipment.

For packaging units of this type, the maximum allowable girth (maxGirth) must be defined.

In addition, carriers also enforce restrictions on maximum length (maxLength) and maximum weight (maxWeight). Optionally, a maximum number of items (maxItemQuantity) can be specified to limit how many articles may be consolidated into a single bulky‑goods shipment.

girth=length+2(width+height)girth = length + 2 (width + height)

Pricing structure and calculation logic

The shipping cost for a bulky goods unit is calculated using the same zone-matching, weight-bracket, and surcharge model as parcel units. Because bulky goods are defined by maxLength and maxGirth rather than three-dimensional box measurements, volumetric weight can't be derived, and no volumetricWeightFactor is applied.

Multi-currency pricing, the overflowFactor, and all configured surchargesPerPackagingUnits apply in the same way as for parcel units.

Example bulky good cost calculation

We'll set the following definitions:

  • Maximum dimension:

    • Maximum length: 200 cm

    • Maximum girth: 300 cm

  • Maximum weight: 31.5 kg

Two-person handling

Definitions and restrictions

This packaging unit type is suitable for heavy or large items that require two-person delivery (for example, furniture). Three-dimensional constraints apply as with parcels. An additional optional maxVolume field is available for carriers that enforce a total cubic volume limit independent of individual dimensions. Also, a maxItemQuantity restriction can be applied here.

Pricing structure and calculation logic

Volume-based pricing tiers define the shipping cost for two-person handling. For the surcharge model, the optional overflowFactor and all configured surchargesPerPackagingUnits are evaluated analogously to the other packagingUnitTypes. The optional maxVolume constraint on the unit determines whether a given set of items is eligible for this packaging unit. Still, it doesn't effect the cost calculation itself.

Example two-person handling cost calculation

We'll set the following definitions:

  • Maximum dimension:

    • Maximum length: 400 cm

    • Maximum width: 230 cm

    • Maximum height: 200 cm

  • Maximum weight: 200 kg

  • Maximum volume: 4 CBM

Create a PackagingUnitDetail by its ID

post

This part of the API is in Beta status. For details please check the api-release-life-cycle documentation. Creates a single PackagingUnitDetail.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

PackagingUnitDetailForCreation

nameLocalizedobject · LocaleStringConstrainedRequired

LocaleStringConstrained

carrierRefstringRequired

The reference to the carrier associated with the packagingUnit.

detailsany ofRequired
or
or
or
tenantPackagingUnitIdstringRequired

The tenant specific identifier for the packagingUnit.

Responses
200

Successfully created the PackagingUnitDetail.

No content
post
/api/packagingunits
No content

Last updated