Location-Based Pricing

Use location-based pricing to adjust prices for customers with a specific shipping address. For example, if you just opened a new branch of your store in a new location and you want to offer a 10% store-wide discount to customers that reside in two specific areas of the city, you can create location-based price rules using an Order Condition. An Order Condition is a custom condition created by the merchant to create price changes based on cart parameters.

Create and apply location-based Order Conditions

To use location-based pricing with an Order Condition, you must:

1. Create the Order Condition using the Create Order Condition API endpoint.
2. Create a ruleset that applies a discount based on the Order Condition you just created.

Step 1: Create the Order Condition

You must create the Order Condition using the Create Order Condition API endpoint.

The following example creates an Order Condition named “ZONE” with a value of Prairies". The Order Condition contains two field_sets, which define the zones where discounts are applied. These field_sets return true if the defined conditions of customer.shipping.country and customer.shipping.postal_code are met.

The operator value "ONE_OF" tells the Price Rules API that only one of the field_sets needs to match for the Order Condition to be valid.

{
  "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

An Order Condition is defined by the combination of name and value. You can not create an Order Condition using the same name and value combination if it already exists. Refer to Create an Order Condition for more information on creating Order Conditions.

Step 2: Create a ruleset with the Order Condition

Once you create an Order Condition using the Create Order Condition API endpoint, you can use it as a condition in a ruleset. An Order Condition in a ruleset contains the following three attributes:

Name	Type	Description
type	string enumeration	The type of condition; for an Order Condition, the type is always ORDER_CONDITION.
name	string enumeration	The name of the Order Condition, defined when you create the Order Condition using the Create Order Condition API endpoint.
value	string enumeration	An attribute to uniquely identify a single Order Condition within an Order Condition group.

note

Both name and value are case-sensitive.

The following condition sets the Order Condition location condition to the “Prairies“ zone:

"conditions": [
    {
        "type": "ORDER_CONDITION",
        "name": "ZONE",
        "value": "Prairies"
    }
],

note

To use the Order Condition within a ruleset, you must use the same name and value attributes that you defined while creating the Order Condition.

The following ruleset uses the Order Condition “Prairies“ from the Order Condition group “ZONE“ to offer a 10% storewide discount to customers with shipping addresses defined in the Order Condition:

{
  "ruleset": {
    "external_id": "Store_Wide_Location_Based_Discount",
    "internal_name": "Store Wide Location Based Discount",
    "product_selection": {
      "type": "PRODUCTS_ALL"
    },
    "rules": [
      {
        "type": "DISCOUNT",
        "conditions": [
          {
            "type": "ORDER_CONDITION",
            "name": "ZONE",
            "value": "Prairies"
          }
        ],
        "actions": [
          {
            "type": "PRICE_ADJUST_PERCENT",
            "value": -10
          }
        ]
      }
    ]
  }
}

When the Order Condition from Step 1 and the ruleset defined in Step 2 are integrated and applied, they give a 10% store-wide discount to any customer with the shipping country as “Canada” and their postal address as either “R3Y0L6” or “R3T5Y3”.

Limitations of using Order Conditions for location-based discounts

There are a few limitations when applying location-based discounts using Order Conditions:

• Since the parameters of an Order Condition are always compared against the shop schema, you cannot include information outside of a shop schema in an Order Condition. The shop schema is a set of interaction data between the shop and customer that the Price Rules Engine (PRE) automatically builds when a browser accesses a PRE-enabled shop. The shop schema only includes certain types of information, so it is not possible to create an Order Condition that checks for data outside of the schema; for example, you cannot create an Order Condition that checks the customer's age or the shop language, because that data is not included in the shop schema. Some common properties included in the shop schema are:
  • Customer name
  • Shipping address (including the postal code)
  • Order number
  • Default shop currency
  • Items the customer has added to their cart
  • Product data for products visible on the current page
• In an Order Condition group, there can never be more than one match. This means that as soon as a match is found in an Order Condition group, that group is considered "solved", even if other Order Conditions in that group are also a match. For example, if you add the same field_set to more than one Order Condition, the Order Condition that first matches that field_set returns true. That Order Condition is "solved" and the rest of the group is not evaluated because the order has already met the criteria to receive the discount.
• Order Conditions within the same group must validate the same fields. Any time you add a new Order Condition or update an already existing one, you must add the same fields.