Broadleaf Microservices
  • v1.0.0-latest-prod

Shipping Common Library

Overview

This library contains DTO structures and a FulfillmentPricingProvider interface for calculating shipping costs.

See the Shipping Services Integrations Documentation for details about the included shipping providers.

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