Documentation

This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official 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 this, is that La Poste does not provide insurance for shipments that are worth more than 1000 EUR. To exclude a Shipping Method from being offered on Carts worth more than 1000 EUR, 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

    As we previously mentioned, in this scenario, we wish to restrict our main Shipping Method if a Cart's value is more than 1000 EUR. To achieve this, we will edit the La Poste Standard Shipping Method and add a predicate which excludes Carts worth more than 1000 EUR. 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 written as followed: totalPrice > "1000.00 EUR". In plain English, this predicate reads: Carts with a total price greater than one thousand Euros.

    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 greater than one thousand Euros, or, a total price greater 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.
    5. Add the Predicate: (totalPrice > "1000.00 EUR" or totalPrice > "11550.00 SEK").
    6. Click Save changes.

    Predicate field within a Shipping Method

    More about predicates

    Create predicates using rule builder

    Writing predicates by hand can sometimes be challenging, however, you may have already written some predicates without even noticing. In the Merchant Center, the Cart discounts page provides an easy-to-use interface dedicated to building predicates. Although the page is primarily used to define Cart Discount predicates, you can also use it to help write Shipping Method predicates.

    To access the predicate rule builder view in the Merchant Center, do the following:

    1. Navigate to Discounts > Cart discount list.
    2. Click Add cart discount.
    3. Scroll to the Under these cart conditions section.
    4. In Editing options, select the code button.
    5. Paste the predicate into the text field (totalPrice > "1000.00 EUR" or totalPrice > "11550.00 SEK").
    6. In Editing options, select the rule builder button.

    You can use the rule builder view to create a predicate, then switch to the code view and copy the predicate that you would like to use in your Shipping Method.

    Predicate Rule Builder View

    When you create a predicate, be sure to use the Under these cart conditions interface and not the Apply these discount effects interface. The Apply these discount effects interface generates predicates, however, only a subset are valid when used on a Cart.

    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