Broadleaf Microservices
  • v1.0.0-latest-prod

FulfillmentPricingService and CommonFulfillmentPricingService

Overview

Service responsible for calculating and populating FulfillmentGroup pricing data. Provides the method applyFulfillmentPricing(Cart, ContextInfo) which totals the fulfillment pricing for each FulfillmentGroup. Ultimately, an implementation should set FulfillmentGroup.groupFulfillmentPriceBeforeAdjustments and FulfillmentGroup.isPriced.

Note
 Fulfillment prices represent the cost of getting the merchandise to the customer. That might be a shipping charge, handling fee, delivery fee, or another type of charge for getting the merchandise to the customer. Fulfillment prices do not include the price of the merchandise itself.

Configuration

CartOperationServiceProperties defines the following configuration properties that affect this service:

  • broadleaf.cartoperation.service.calculateFulfillmentPricingWithAdjustments: Determines whether the fulfillment pricing should consider the adjustments on the order and order items. Default is true. Deprecated in CartOps 1.8.9-GA (RELEASE TRAIN 1.8.2-GA)

  • broadleaf.cartoperation.service.calculateProratedFulfillmentPricing: Determines whether the fulfillment pricing should consider prorated price of the order items, after factoring in the order adjustments. Default is true.

CommonFulfillmentPricingService

Introduced in CartOps 1.8.9-GA (RELEASE TRAIN 1.8.2-GA)

The CommonFulfillmentPricingService totals the prices from the PricedFulfillmentOptions on FulfillmentGroups or FulfillmentItems and sets the appropriate FulfillmentGroup fields.

The interface CommonFulfillmentPricingService was added in version CartOps 1.8.9-GA (RELEASE TRAIN 1.8.2-GA) to provide a common interface for aggregating fulfillment pricing data from either FulfillmentOption or the new PricedFulfillmentOption. The pre-exising FulfillmentPricingService now extends CommonFulfillmentPricingService.

Note
 For overall pricing, see CartPricingService.

External Fulfillment Provider

By default, the FulfillmentOptionRequestService defers to the ExternalFulfillment provider to get fulfillment options, prices, and configuration.

PricedFulfillmentOption

PricedFulfillmentOption holds specific fulfillment price and service level for its corresponding group or item.

Front End Integration Recommendation

By default, it is intentional to not refresh the priced fulfillment option on every cart change. Because of this, if the customer has selected an option and then changed the cart, then the customer must be forced to select a new fulfillment option if the currently selected option does not match any available option.

This is needed to prevent the validation error that indicates that the selected option is stale/unavailable.

For example:

    import { find, isEqual } from 'lodash';

    // get the current selected option
    const { pricedFulfillmentOption: selectedPricedFulfillmentOption } = cart.fulfillmentGroups[0];

    // load available options for the cart
    const { fulfillmentOptions } = useFetchFulfillmentOptionsForCartItems(submitting);

    const pricedOptionsContainGroupOption = find(
            fulfillmentOptions,
            option => isEqual(option, selectedPricedFulfillmentOption)
          );
    if(pricedOptionsContainGroupOption) {
        // the current selected option is available for the cart
        // it is not required to select the new one
    } else {
        // force customer to select the new option
    }

FulfillmentServices Calculators

The Fulfillment Calculators in FulfillmentServices have complete control over how to calculate the price for a FulfillmentGroup. Configuring individual calculators can be done in the admin or with a code-based calculator.

FulfillmentPricingService

Deprecated in CartOps 1.8.9-GA (RELEASE TRAIN 1.8.2-GA)

The FulfillmentPricingService applies the prices from the FulfillmentOption on FulfillmentGroup to the appropriate pricing fields on that FulfillmentGroup.

In version CartOps 1.8.9-GA (RELEASE TRAIN 1.8.2-GA), the FulfillmentPricingService was updated to implement CommonFulfillmentPricingService. This does not affect any functionality in FulfillmentPricingService or DefaultFulfillmentPricingService.

External Shipping Provider

Deprecated in CartOps 1.8.9-GA (Release Train 1.8.2-GA)

By default, this pricing service delegates to the ExternalShippingProvider to get fulfillment rates from Shipping Services. Shipping Services has multiple types of providers configurable out-of-the-box. For instance:

  • FixedFulfillmentPricingProvider - Provides simple fixed fulfillment pricing based on a configuration file.

  • BandedFulfillmentPricingProvider - Provides banded or tiered fulfillment pricing where the tiers are based on a minimum price or weight.

  • VirtualFulfillmentPricingProvider - Provides simple fixed fulfillment pricing based on a configuration file for virtual fulfillment.

  • ShipEngineFulfillmentPricingProvider - Integrates with ShipEngine to provide fulfillment prices and labels.

See Shipping Service Integrations for more details.

FulfillmentOption

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.

Tip
 see FulfillmentOption javadocs.

Deprecated in CartOps 1.8.9-GA (RELEASE TRAIN 1.8.2-GA)

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

Deprecated in CartOps 1.8.9-GA (RELEASE TRAIN 1.8.2-GA)

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.