Broadleaf Microservices
  • v1.0.0-latest-prod

Broadleaf Shipping Services


Manages shipping configuration and calculation.

Data Model

See the Data Model for information on the key domain classes used by the shipping service.

Key Components

  • FulfillmentPricingProvider - Interface to provide fulfillment pricing.

  • ShippingLabelProvider - Interface to provide shipping labels.

  • FulfillmentPricingService - Provides fulfillment prices for carts during checkout.

  • ShippingLabelProviderService - Provides shipping labels for orders in the admin.

  • WeightCalculationService - Enables calculating shipping weight for items with different weight units.



Interface defining a service that provides fulfillment options and pricing calculations appropriate for a request.

Three simple implementations are included that only require maintaining a JSON configuration file. For more advanced needs, we have a ShipEngine integration out-of-the-box. For complete control, implement a new FulfillmentPricingProvider with custom logic or 3rd party integration.

Get Options with Pricing and Estimated Fulfillment Date

To get a list of available fulfillment options and the estimated prices for each, use #getFulfillmentOptionPricingResponses. The method takes a FulfillmentPricingRequest and returns a list of FulfillmentOptionPricedResponses. The particular implementation will handle determining the options that fit the request—typically, only the items, currency, and ship-to address are necessary.

To retrieve the list from a frontend client call the Get Fulfillment Options Endpoint

Price Fulfillment Group

To price a specific FulfillmentGroup, use either #estimateCostForFulfillmentGroup or #calculateCostForFulfillmentGroup, depending on whether you want an estimate. Both take a FulfillmentPricingRequest and return a single FulfillmentOptionPricedResponse. These are typically called after a specific FulfillmentOption has been selected by a customer. To get the options with prices and estimated fulfillment date, use #getFulfillmentOptionPricingResponses.

Included Fulfillment Pricing Providers




A fulfillment option is used to hold information about a particular type of fulfillment implementation. Third-party fulfillment implementations should extend this to provide their own configuration options particular to that implementation. For instance, a UPS shipping calculator might want an admin user to be able to specify which type of UPS shipping this FulfillmentOption represents.

Options might include standard shipping, express, same-day, etc.


To retrieve the list of options as a frontend client, call the Get Fulfillment Options Endpoint, which uses the FulfillmentPricingService to get the list of applicable options for a fulfillment group. This provides the description of the option for the customer as well as the calculated price of using that option.


Fulfillment options can be configured a number of ways depending on the provider. However, at their most basic, they have the following properties:

  • name: This should be unique across all options and is used as an identifier.

  • description: This is used to describe the option to the customer

  • useFlatRates: Whether to use flat rates for this option. Default is false.

  • taxCode: The tax code for the option

  • taxable: Whether price for this option is taxable Default is false.


Represents a group of items whose fulfillment to price along with all relevant contextual information required to determine the pricing. It includes the following fields:

  • fromAddress: "Ship from" address

  • toAddress: "Ship to" address

  • currency: Cart or Order currency

  • fulfillmentPricingItems: List of items to be fulfilled

  • fulfillmentOption: Optional name of a fulfillment option, e.g., FIXED_STANDARD, BANDED_PRICE_STANDARD, DOWNLOAD

  • customer: Optional customer ID or email

  • attributes: Optional list of miscellaneous attributes


Represents the fulfillment pricing info for FulfillmentPricingRequest. It includes the all of the FulfillmentOption fields along with:

  • fulfillmentPriceCalculated: The calculated fulfillment price total

  • estimatedDeliveryDate: Estimated delivery date

  • fulfillmentPriceInfos: A breakdown of the pricing per item mapping the item ID to a FulfillmentPriceInfo


Represents the fulfillment pricing information for a single line item. It includes the following fields:

  • itemId: ID of the cart or order line item

  • skuCode: SKU for the merchandise item—e.g., of the Product or Variant

  • isEstimated: Whether the price is an estimate or final

  • pricePerUnit: Price for fulfilling a single unit in the line item

  • total: Price for fulfilling all units in the line item


ShipmentDetails link an OrderFulfillment to shipping data. The fields are generic and not specific to any implementation. The ShipEngine integration uses ShipmentDetails to store label ids of purchased shipping labels.

Sandboxing Configuration

At the time of this writing, there’s no sandboxable entities in this service. If a sandboxable entity is introduced in this service, the following configurations should be added:

              group: shipping-purge-sandbox
              destination: triggeredJobEvent
     enabled: true
       active: true
         enabled: true

See Sandboxing In Detail for more details.

These configurations typically only affect the Granular Deployment model. For Min and Balanced deployements, these configurations are likely already added at the flexpackage-level configuration.