Documentation

Using Predicates on Shipping Methods

This tutorial shows how you can express your business specific logic for which shipping methods should be offered for a cart during checkout. This is achieved by setting Predicates on Shipping Methods.

When is a predicate needed on a Shipping Method?

If you operate with a series of possible shipping methods, but not all shipping methods should be considered valid options for every cart, predicates on shipping methods allow you to define such logic.

Examples of such rules:

  • Shipping Method "DHL Express" should only be offered for carts with line items that are eligible for express shipping
  • Shipping Method "Fedex Premium" should not be offered to a certain segment of the customers
  • Shipping Method "UPS" is the only method suitable for carts with bulky items weighing more than 10 kg

How to use predicates on Shipping Methods?

Similar to the use of predicates on discounts to express discount rules, predicates on shipping methods are used to express shipping method rules. Adding a predicate to a shipping method defines a criteria that the cart has to fulfill in order for the shipping method to be a valid option. When shipping methods are retrieved for a given cart, the cart will be evaluated against the given shipping method predicate. Only if the cart matches the criteria of a shipping method, the shipping method will be offered during checkout.



// matches a cart when at least one line item has the custom field attribute "eligible_for_express_shipping" set to TRUE
lineItemExists(attributes.eligible_for_express_shipping = true)


// matches a cart for all customer group except one
customerGroup.id != "f6a19a23-14e3-40d0-aee2-3e612fcb1bc7"


// matches a cart when at least one line item has the custom field attribute "bulky" set to TRUE and when at least one line item has the custom field attribute "weightInKilograms" set to a value greater than 10
lineItemExists(attributes.bulky = true) and lineItemExists(attributes.weightInKilograms > 10)

The predicate language contains a list of logical operators and functions that can be used to express the condition of a shipping method rule.

How are Shipping Method predicates evaluated during a checkout?

When a cart has been created and Get ShippingMethods for a Cart is called, the response to this call will only include the shipping methods that, upon predicate evaluation, qualify as valid shipping methods.

Should a cart be updated in such a way that the conditions of the cart no longer match the criteria of the shipping methods set in the cart, the parameter shippingMethodState found under the cart's ShippingInfo will switch from MatchesCart to DoesNotMatchCart. If you try and create an order from a cart that has ShippingMethodState with DoesNotMatchCart, the order creation will be rejected.

If Set ShippingMethod is called and the shipping method that is attempted to be set does not match the condition of the cart, the call will be perceived as an invalid operation and be rejected.