Broadleaf Microservices

Shipping Common Library

Overview

This library contains DTO structures and a FulfillmentPricingProvider interface for calculating shipping costs. It also contains three simple implementations:

Using one of these simple implementations requires maintaining a JSON configuration file. Otherwise, a shipping provider integrated with a 3rd party, such as ShipEngine, is preferred.

This library is used by Cart Operations Services to determine fulfillment pricing for carts.

Key Components

FulfillmentPricingProvider

Overview

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

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.

Note
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.

Domain

FulfillmentOption

Overview

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.

Usage

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.

Configuration

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.

FulfillmentPricingRequest

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

FulfillmentOptionPricedResponse

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

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