Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Add-to-cart and purchase validation

Add-to-cart and purchase validation

When you update or check out your cart, Commerce Engine performs a number of checks to ensure that the action is valid and the system can complete the action. If the action is invalid, Commerce Engine returns StructuredErrorMessage objects, with an optional StructuredErrorResolution embedded in them through the call stack to the user.

The com.elasticpath.service.shoppingcart.validation package provides a generic interface, Validator, as well as interfaces intended for more specific purposes, such as ProductSkuValidator. These interfaces are implemented for specific validation cases and aggregated by a set of service classes, which are called at specific parts of the purchasing workflow.

The service classes are:

  • AddProductSkuToCartValidationService: Determines if a product SKU can be added to a cart. Invoked when the add to cart form is retrieved.
  • AddOrUpdateShoppingItemDtoToCartValidationService: Determines if a ShoppingItemDto or ShoppingItem object can be added to a cart, or whether an existing ShoppingItemDto or ShoppingItem can be updated. A ShoppingItem object represents a specific quantity of a product SKU. Invoked when a client sends a POST request to the add to cart action link or a PUT request to a cart line item to update it.
  • PurchaseCartValidationService: Determines if a shopping cart can be purchased. Invoked when the purchase form is retrieved and when a client sends a POST request to the purchase cart action link.

ProductSku validators

The AddProductSkuToCartValidationService class aggregates validators that implement the ProductSkuValidator interface and validate whether a product SKU can be added to a cart. The validators are:

Validator Validation Performed StructuredErrorMessage ID
AutoSelectable BundleConstituent DelegateValidatorImpl Runs all product SKU validators except SoldSeparatelyProductSku ValidatorImpl on bundle constituents that are automatically added to the cart. A StructuredErrorMessage ID returned by a ProductSkuValidator implementation, depending on the validation failed.
ProductSkuDates ValidatorImpl Validates product SKU start and end dates. item.no.longer.available, item.not.yet.available
SoldSeparatelyProductSku ValidatorImpl Validates that a product SKU can be sold separately. item.not.sold.separately
PriceExistsProductSku ValidatorImpl Validates that a product SKU has a price assigned to it. item.missing.price
VisibleProductSku ValidatorImpl Validates that a product SKU is visible in the store. item.not.visible
InventoryProductSku ValidatorImpl Validates that the product SKU has unallocated inventory which can be added to a cart. item.insufficient. inventory
InCatalogProductSku ValidatorImpl Validates that the product SKU is in the store's catalog. item.not.in.store.catalog

ShoppingItemDto validators

The AddOrUpdateShoppingItemDtoToCartValidationService class aggregate validators that implement the ShoppingItemDtoValidator or ShoppingItemValidator interfaces. Validators that implement ShoppingItemDtoValidator validate a specific quantity of a product SKU before it is added to the cart.

The validators are:
Validator Validation Performed StructuredErrorMessage ID
BundleMaxSelection RulesShoppingItem DtoValidatorImpl Validates whether the maximum allowed number of constituents for the bundle is exceeded by adding an item to the cart. bundle.exceeds.max. constituents
BundleStructure ShoppingItem DtoValidatorImpl Validates whether the cart item contains dependent line items that are invalid for the bundle's defined structure. item.invalid.bundle. structure
CartItemModifier ShoppingItem DtoValidatorImpl Validates that the cart item modifiers are correct for a ShoppingItemDto object.
InventoryShopping ItemDtoValidatorImpl Validates that there is sufficient inventory to add a specific quantity of an item specified in a ShoppingItemDto object to a cart item.insufficient. inventory
QuantityShopping ItemDtoValidatorImpl Validates that the minimum allowable quantity for a product is added. When adding an item to a cart, the minimum quantity is 1. When updating an existing item in a cart, the minimum quantity is 0. field.invalid. minimum.value

ShoppingItem validators

The AddOrUpdateShoppingItemDtoToCartValidationService class aggregate validators that implement the ShoppingItemDtoValidator or ShoppingItemValidator interfaces. Validators that implement ShoppingItemValidator validate a specific quantity of a product SKU after it is added to the cart.

The validators are:

Validator Validation Performed Structured Error Message ID
BundleMinSelection RulesShoppingItem ValidatorImpl Validates that the bundle in a cart has the minimum required constituents. bundle.does.not.contain. min.constituents
CartItemModifier ShoppingItem ValidatorImpl Validates that the cart item modifiers are correct for a ShoppingItem object.
InventoryShopping ItemValidatorImpl Validates that sufficient inventory to add a specific quantity of an item specified in a ShoppingItem object to a cart is available. item.insufficient. inventory
ProductSkuDelegate FromShoppingItem ValidatorImpl Runs all product SKU validators for the product SKU in the ShoppingItem object. A StructuredErrorMessage ID returned by a ProductSkuValidator implementation, depending on the validation failed.

ShoppingCart validators

The PurchaseCartValidationService class aggregates the following validators that implement the ShoppingCartValidator interface and validate whether a shopping cart and its constituent shopping items can be purchased.

The validators are:

Validator Validation performed StructuredErrorMessage ID
BillingAddressShopping CartValidatorImpl Validates that a billing address is specified for the cart. need.billing.address
EmailAddressShopping CartValidatorImpl Validates that an email address is specified for the cart. need.email
EmptyShoppingCart ValidatorImpl Validates that the cart is not empty. cart.empty
GiftCertificateBalance ShoppingCartValidatorImpl Validates that gift certificates specified as a payment method exist and have a sufficient balance to complete the purchase. cart.gift. certificate.not.found, cart.gift.certificate. insufficient.balance
PaymentMethodShopping CartValidatorImpl Validates that a payment method is specified for the cart. need.payment.method
ShippingAddressShopping CartValidatorImpl Validates that a valid shipping address is specified for the cart if the cart contains physical SKUs. need.shipping.address
ShippingOption ShoppingCartValidatorImpl Validates that a valid shipping option is specified for the cart if the cars contains physical SKUs. need.shipping.option, invalid.shipping.option, shipping.options. unavailable
ShoppingItemDelegate FromShoppingCart ValidatorImpl Runs all shopping item validators on all items in the cart. A StructuredErrorMessage ID returned by a ShoppingItemValidator implementation, depending on the validation failed.

Creating or overriding a cart or purchase validation

To customize the validation strategies or features do the following:
  1. Extend the appropriate validator in the com.elasticpath.service.shoppingcart.validation package and override the validate() method.
  2. Add the validator's bean definition to /ep-commerce/commerce-engine/core/ep-core/src/main/resources/spring/service/validation-strategies.xml file.
  3. Add the validator to the appropriate validation list in the validation-strategies.xml file.