Create an Order Condition

An ORDER_CONDITION is a custom condition created by the merchant to create price changes based on cart parameters. Cart parameters are attributes related to a specific customer that Price Rules is able to recognize (see table below for supported cart parameters). A common use case of Order Conditions is to create "zones", allowing the merchant to create different discounts based on the customer's shipping data they’ve entered.

Cart Param	Description	Example
`customer.shipping.country`	The customer's country, from the information they entered into "shipping address".	Canada
`customer.shipping.country_code`	The customer's country code, from the information they entered into "shipping address".	CA
`customer.shipping.postal_code`	The customer's postal code, from the information they entered into "shipping address".	R3Y0L6
`customer.shipping.province`	The customer's province, from the information they entered into "shipping address".	Manitoba
`customer.shipping.province_code`	The customer's province, from the information they entered into "shipping address".	MB

When you create an Order Condition, you are really creating a custom condition and specifying which conditions will evaluate to true. This is done by providing field sets. Take a look at the example of a body for creating an Order Condition with field sets below:

{
  "name": "ZONE",
  "value": "Prairies",
  "operator": "ONE_OF",
  "type": "FIELD_SET",
  "field_sets": [
    {
      "customer.shipping.country": "Canada",
      "customer.shipping.postal_code": "R3Y0L6"
    },
    {
      "customer.shipping.country": "Canada",
      "customer.shipping.postal_code": "R3T5Y3"
    }
  ]
}

note

name and value are case sensitive.

Here, we are saying that this new condition called "Prairies" for the Order Condition named "ZONE" will evaluate to true if one of the two possible conditions are met: The customer's shipping address is "Canada" and postal code "R3Y0L6" OR The customer's shipping address is "Canada" and postal code "R3T5Y3".

note

An Order Condition is defined by the name and value together, you cannot create new Order Conditions using the same name and value if that combination already exists. Also note that name and value are case sensitive.

Explanation

The name is what we want to call our Order Condition, it will be used when we create our ruleset. So when we create our rule, we will tell it that we want to check the ZONE condition. If you had multiple zones, you would make sure each Order Condition shared this name to create a group.

The value is what we want to call this particular Order Condition. This Order Condition that we just created will be called "Prairies", so you could make another one such as "West Coast", being sure to use appropriate postal codes.

The operator with value of ONE_OF tells Price Rules that only one of the field sets needs to match for this condition to be met. This is the only operator supported at this time.

The field_sets are optional when creating the Order Condition and could be modified at a later point, each item in this array is a single condition that, when met, will evaluate this condition to true because we are using the ONE_OF operator.

Order Condition Groups

A single Order Condition is defined by a name and value. When you have multiple Order Conditions sharing the same "name", this would make an Order Condition Group.

For example, a shop could have an Order Condition Group made of the following Order Conditions:

name: "DeliveryZone", value: "Fort Garry"
name: "DeliveryZone", value: "Assiniboine"
name: "DeliveryZone", value: "Seven Oaks"
name: "DeliveryZone", value: "St. Boniface"

How does it work?

When a customer visits a page with a product on it, Price Rules checks the rules it has for that product and applies any changes if conditions of any rulesets are met. For Order Conditions, Price Rules checks the "shop schema" behind the scenes as part of it's rule evaluation. The shop schema contains shop-related info such as the shop’s currency, items in the cart and customer info.

note

Order Conditions are evaluated in order by name. This means that if you had two Order Conditions "Prairies" and "West Coast", then "Prairies" will be evaluated first. This won’t usually be an issue since the field sets for each should be unique, therefore both will be evaluated.

However, if the conditions were broad enough and field sets belonging to different Order Conditions will both evaluate to true, then the one belonging to the Order Condition that comes first alphabetically will be taken.

As an example, let's say that "DeliveryZone: Fort Garry" contains some field sets like:

"field_sets": [
    {
      customer.shipping.country_code: "CA"
      customer.shipping.postal_code: "R3Y0L6"
      customer.shipping.city: "Winnipeg"
    },
    {
      customer.shipping.country_code: "CA"
      customer.shipping.postal_code: "R3T5Y3"
      customer.shipping.city: "Winnipeg"
    },
    {
      customer.shipping.country_code: "CA"
      customer.shipping.postal_code: "R3P2M4"
      customer.shipping.city: "Winnipeg"
    }
]

The service identifies the relevant attributes as: customer.shipping.country_code, customer.shipping.postal_code and customer.shipping.city. It then checks these fields inside the shop schema.

If there is a field set that is equivalent to the received shop data, its Order Condition name and value are added to a list. After all Order Condition groups are processed, the list will be returned to the frontend and saved inside the shop schema for future use.

Match was found

If a field set matched for "DeliveryZone: Fort Garry", then it will be included in the list to be returned. This group is considered solved, so the other conditions (listed below) will never be evaluated:

name: "DeliveryZone", value: "Assiniboine"
name: "DeliveryZone", value: "Seven Oaks"
name: "DeliveryZone", value: "St. Boniface"

Match wasn’t found

If no field set matched for "DeliveryZone: Fort Garry", then the other conditions in the group will be evaluated next.

Multiple Groups

If there are other conditions for that shop that are not part of the resolved group (e.g. Order Conditions with a name other than "DeliveryZone"), then the same evaluation process will occur until there are no more to evaluate. The matches will be returned to the storefront via an updated shop schema.

Limitations

I. Since the Order Condition is always compared against the shop schema, information that does not exist in the shop schema can't be included in an Order Condition to be evaluated. Therefore it's not possible to create an Order Condition that checks the customer age or the shop language, you may only use the values in the table mentioned above.

II. There can't be more than one match for the same Order Condition group. As soon as a match is found, that group is considered solved, even if other Order Conditions in the same group are also a match (e.g. if the same field set is added to more than one Order Condition).

III. Order Conditions within the same group must validate the same fields. Every new Order Condition belonging to the group, or updates within the group, will be forced to include the same fields.

Examples

As an example, let's say we want to give customers that live within a certain zone a 50% off, store-wide discount. By using an Order Condition, we can define the zone, then create a rule that provides the discount.

1. Create Order Condition

We'll use following payload to create "field sets" to define the zones we are interested in for this rule. This will be sent using the Create Order Condition API call.

{
  "name": "ZONE",
  "value": "Prairies",
  "operator": "ONE_OF",
  "type": "FIELD_SET",
  "field_sets": [
    {
      "customer.shipping.country": "Canada",
      "customer.shipping.postal_code": "R3Y0L6"
    },
    {
      "customer.shipping.country": "Canada",
      "customer.shipping.postal_code": "R3T5Y3"
    }
  ]
}

2. Create Rule With Order Condition

To use the Order Condition, you simply create a rule as you normally would, using the name and value we assigned when we created the Order Condition.

{
  "ruleset": {
    "external_id": "OC_Test",
    "internal_name": "OC_Test",
    "product_selection": {
      "type": "PRODUCTS_ALL"
    },
    "rules": [
      {
        "type": "DISCOUNT",
        "conditions": [
          {
            "type": "ORDER_CONDITION",
            "name": "ZONE",
            "value": "Prairies"
          }
        ],
        "actions": [
          {
            "type": "PRICE_ADJUST_PERCENT",
            "value": -50
          }
        ]
      }
    ]
  }
}

Order Condition Groups​

How does it work?​

Match was found​

Match wasn’t found​

Multiple Groups​

Limitations​

Examples​

1. Create Order Condition​

2. Create Rule With Order Condition​

Order Condition Groups

How does it work?

Match was found

Match wasn’t found

Multiple Groups

Limitations

Examples

1. Create Order Condition

2. Create Rule With Order Condition