Documentation

Predicates

Learn how to use predicates to define Shipping Method eligibility for Carts.

  • After completing this page, you should be able to:

    • Describe how a Cart determines which Shipping Methods are available.
    • Explain how predicates can be used with a Shipping Method.

    • We have one final Shipping Method to set up for Electronics Company. In this scenario, Electronics Company needs to set a specific Shipping Method based on the value of the goods in the Cart.

    The reason for wanting to do this is that La Poste does not provide insurance for shipments worth 1000 Euro or more. To ensure that a specific Shipping Method is only offered on certain Carts, we need to use a predicate.

    Before you start, we recommend reviewing the following pages in our documentation, which explain how predicates work.

    Scenario 4: Restricting the Shipping Method based on Cart information

    To restrict this Shipping Method based on Cart information, we will edit the La Poste Standard Shipping Method and define a predicate. Let's do it together.

    Define our predicate

    In this scenario, we target the totalPrice field and define the amount as 1000 EUR. For example, our predicate is: totalPrice < "1000.00 EUR". In plain English, this predicate reads: Carts with a total price less than 1000 Euro.

    This predicate restricts the Shipping Method, but only for Carts with a currency set to Euros. Since we also offer customers the ability to shop using Swedish Krona (SEK), we need to add an additional condition to the predicate. You can combine conditions within a predicate by using either the AND or the OR operators. In our case, we will use the OR operator.

    Let's rewrite the predicate to cover both currencies:

    totalPrice < "1000.00 EUR" or totalPrice < "11550.00 SEK"

    In plain English, this predicate reads: Carts with a total price less than 1000 Euro, or, a total price less than eleven thousand five hundred and fifty Swedish Krona.

    Update the Shipping Method

    Now that we are clear about the predicate to use, we can update the Shipping Method with it in the Merchant Center:

    1. Navigate to Settings > Project settings.
    2. Click the Shipping Methods tab.
    3. Select the La Poste Standard Shipping Method.
    4. Scroll to the Predicate field. Here you have two options:
      1. Add the predicate in the Predicate field: totalPrice < "1000.00 EUR" or totalPrice < "11550.00 SEK". Predicate field within a Shipping Method
      2. Use the Shipping Methods predicate builder to create the predicate via an easy to use user interface. Predicate builder within a Shipping Method You can easily switch between the options by selecting the Editing options toggle.
    5. Click Save changes.

    Predicate evaluation

    Composable Commerce evaluates each Shipping Method predicate when a Cart is created and offers only valid Shipping Methods. It's possible that a change to a Cart may cause the selected Shipping Method to become invalid. In this case, an Order can not be created until another shipping method is chosen.

    To find the all valid Shipping Methods for a Cart, use the Get matching Shipping Methods endpoint. To check if the assigned Shipping Method on a Cart is still valid, you can use either the Cart Recalculate or My Cart Recalculate update actions.

    Common use cases

    By now, you can start to see power and flexibility of using predicates with Shipping Methods. Let's take a look at one more common use case.

    Shipping within large countries

    Certain countries, such as the United States, or Australia, cover large geographical areas, which makes shipping more complex. The rate charged by the carrier is often dependent on the distance to the receiver.

    For example, an Australian business that has a distribution center in New South Wales (located in the east of the country), needs to offer alternative Shipping Methods and shipping rates to addresses in Western Australia due to the distances involved. A common way to approach this scenario would be to use predicates on the states of a country.

    When writing predicates for this scenario, we will use shorthand values for the states of Australia. For example, instead of writing New South Wales, we will write NSW. Our specific Project design assumes that the front-end saves the state values as shorthand. If we do not use the shorthand in the predicate, then it would not work in the intended way. It is important to be aware of Project specific assumptions and naming conventions in your particular commerce implementation.

    To create a solution for this scenario, do the following:

    1. Create a Zone for Australia called AUS.

    2. Create two individual Shipping Methods, each with the AUS Zone added:

      • Standard Delivery (East): We will use the following predicate: shippingAddress.state in ("NSW","VIC","QLD"). In plain English, this reads: The shipping address state is New South Wales, Victoria, or Queensland.

      • Standard Delivery (West) We will use the following predicate: shippingAddress.state in ("WA"). In plain English, this reads: The shipping address state is Western Australia.

    With these predicates in place, the customer is shown only the Shipping Method(s) which are available for their particular state.

    Test your knowledge