Broadleaf Microservices
  • v1.0.0-latest-prod

Key Customer Service Components

Messaging Components


The Customer Service maintains a list of PersistenceHandler implementations. It loops through the list of registered handlers and determines which one can process a given persistence event.

Here is an example list of handlers that are worth noting:

  • CreatePaymentAccountEventListener - An event listener that triggers when an order is successfully submitted. Responsible for checking the completed cart for any newly specified payment methods that the user wishes to save for future usage or usage of any previously saved payment methods to record the latest results.

    • Since 1.7.2, the default value for is set to BLC_PAYMENT_TRANSACTION_SERVICES, which means PaymentAccount-related beans will not be registered (including this listener).

      • To continue using CustomerServices to store saved payment methods, set this property to BLC_CUSTOMER_SERVICES (see behavior configuration docs for more details). If CustomerServices is used to store saved payment methods, then the following message binding should be added to the configuration:

                        group: customer-checkout-completion
                        destination: checkoutCompletion

        Additionally, the following spring cloud messaging configuration can be removed from PaymentTransactionServices:

                  group: payment-transaction-checkout-completion
                  destination: checkoutCompletion
    • Since PaymentTransactionServices 1.0.2, the creation of saved payment methods as a portion of the checkout process is now handled via a post-transaction hook. If the saved payment method storage location is BLC_CUSTOMER_SERVICES, then this listener should only be enabled for a time to handle any existing messages whose saved payment methods were not created via the PaymentTransactionServices hook. Once a day or two have passed after adopting the PaymentTransactionServices upgrade, this listener can be disabled by declaring broadleaf.customer.messaging.payment-account.create.enabled=false, see create payment account event properties docs for more details.

  • UserCreationListener - An event listener that responds to a UserCreatedEvent that updates the Customer based on the provided User data

  • UserRegistrationListener - Listens to customer user registration events and creates a new corresponding Customer


CustomerImportMessagingAutoConfiguration registers standard listener components required to support the default import implementations.


This service includes several out-of-box import implementations.

Customer Import

The import type is CUSTOMER, and the corresponding specification in ImportServices is CustomerSpecification.

  • CustomerImportBatchHandler is responsible for processing imports of Customer entities.

  • CustomerConverter is responsible for converting input customer rows into Customer instances.

  • (since 1.8.3) CustomerAddressColumnConverter is responsible for converting address-related columns from input customer rows into CustomerAddress instances

Default Billing and Shipping Customer Address Management

(since 1.8.3)

On each customer row, address fields can be supplied to define the default billing and shipping address for the customer.

  • The CustomerAddressColumnConverter expects all address-related fields to start with address:: as the prefix. The expectation is for the CustomerSpecification in ImportServices to have already performed this mapping.

  • Specifying address information is entirely optional, but if any address:: field is provided, the user must also provide the address name field.

    • The name field is used as the 'unique key' to find an existing matching address to update. If no pre-existing address with the given name exists for the customer, a new address will be created.

      This means the address' name itself cannot be updated via this import.
  • The provided address will always be force-set as the default billing and shipping address for the customer. Any existing addresses which are currently the default billing or shipping address will be unset as such.

  • The CustomerAddress instance will be initialized from both the provided address fields and the parent customer information.

    • The following fields are force-set on the address instance using values from the customer

      • Parent customer ID reference

      • Email address

      • If the customer uses the full name field, then it is used, otherwise the first and last name fields are used

      • Primary phone number

    • All other fields are honored from input, assuming the specification defines a mapping for them to the address::{field} format

Customer Segment Member Import

The import type is CUSTOMER_SEGMENT_MEMBER, and the corresponding specification in ImportServices is CustomerSegmentMemberSpecification.

  • CustomerSegmentMemberImportBatchHandler is responsible for processing imports to associate provided Customer records to a CustomerSegment via SegmentMember entities.

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: customer-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.