Skip to content
On this page

Optimizing and mastering rules

WARNING

This feature is not available during the free trial.

Working with rules

Rules work as a group set.

These groups are:

  • 🗓 Date
    • Min date
    • Max date
  • 🏷 Prices
    • Total amount of the receipt
    • Minimum amount spent on a given product(s)
  • 🏬 Signs
  • 🛍 Items (aka Products)
    • Product names and brands to be found in the receipt
    • Minimum number of items to find in a receipt

Each group is checked separately one-by-one by our validation system.

WARNING

A receipt will only be considered valid (or eligible) if it complies with all rule groups.

These groups allow our system to give you detailed report about which rules have matched for the receipt and which have not.

Let's take a closer look at the JSON format of each of the rule group

🗓 Date

json
{
  "dateRule": {
    "min": "2019-01-01",
    "max": "2019-11-01"
  }
}

Here the min key corresponds to the minimum date allowed for the receipt and the max key is the maximum date.

TIP

Date format must respect the ISO8601 standard without time.

🏬 Sign

json
{
  "signRule": {
    "signList": [
      "Cora",
      "Auchan",
      "Carrefour"
    ]
  }
}

The signList key is an array of string, where each string corresponds to a store sign.

A sign is the name of a retailer. The rule will be validated only if the receipt's store is in the list of signs (aka signList).

You can retrieve here the list of possible value to pass in this array, as we have a fixed list of signs that can be detected by our system.

🛍 Item

Before using an itemRule please note the following structure of an item:

json
{
  "term": "Sodebo",
  "quantityRequired": 2,
  "strategy": "QUANTITY"
}

An itemRule is an object which may contain multiple items:

json
{
  "itemRule": {
    "or": [
      {
        "term": "Tarama"
      },
      {
        "term": "Blini"
      }
    ],
    "quantityRequired": 2,
    "strategy": "QUANTITY",
    "not": [
      {
        "term": "Boursin"
      },
      {
        "term": "Sodebo"
      }
    ]
  }
}

DANGER

The or and and keys are mutually exclusive. You can't have an or key with an and key.

json
{
  "itemRule": {
    "and": [
      {
        "term": "Labeyrie"
      }
    ],
    "quantityRequired": 2,
    "strategy": "QUANTITY",
    "not": [
      {
        "term": "Sodebo"
      },
      {
        "term": "Bordeaux chesnel"
      }
    ]
  }
}
  • The quantityRequired corresponds to the minimum number of item required for this eligible products
  • The strategy key correspond to the strategy used to count item for the key quantityRequired, this key can only equal to one of these three values:
    • QUANTITY will only check for the quantity of an item

      Example: 1 pack of 6 beers, quantity is 1

    • BUNDLE will only check for the bundle size of an item

      Example: 1 pack of 6 beers, bundle will be 6

    • QUANTITY_TIMES_BUNDLE will check and multiply the two previous values, quantity multiplied by bundle to get the number of products bought

      Example: 2 packs of 6 beers, the quantity will be 6x2 => 12

  • The not key is an array of item with each item corresponding to a product label to be excluded from the list of eligible products. This is useful in the case where a competitor's brand owns a product whose name is too similar to the one we want to detect.
  • The or is the most important and useful key. It's an array of item. A term has a string value. Each value represents a potential product label that we want to detect. The receipt will be considered valid if any of the label has been detected according to the required quantity
  • The and key : It's also an array of item. A term has a string value. Each value represents a product label that must be present at least once per label in the receipt.

🏷 Price

json
{
  "priceRule": {
    "eligibleOnly": 20.25,
    "totalAmount": 40
  }
}
  • The eligibleOnly key is minimum amount spent on eligible products.
  • The totalAmount key is the total amount of the receipt.

How to know if a receipt is eligible?

As mentioned above each rule group is checked separately. In each group there is an isMatched key. If this key is true then the value in the field has been found in the receipt.

In the following example the terms Labeyrie and Blini in the or group have been found which is one of the conditions to make a receipt eligible. But we also found Auchan in the not group which removes the matched item from the list of eligible items.

TIP

To see if the receipt is eligible at first glance, you only need to check the allRulesMatched key. If the value is true then the receipt is eligible.

json
{
  "name": "Labeyrie",
  "uid": "123",
  "itemRule": {
    "quantityRequired": 2,
    "strategy": "QUANTITY",
    "or": [
      {
        "term": "Labeyrie",
        "quantityRequired": 1,
        "itemsMatched": [
          "3"
        ],
        "isMatched": true,
        "quantityMatched": 1
      },
      {
        "term": "Blini",
        "quantityRequired": 1,
        "itemsMatched": [
          "1",
          "2"
        ],
        "quantityMatched": 2,
        "isMatched": true
      }
    ],
    "not": [
      {
        "isMatched": true,
        "term": "Auchan",
        "itemsMatched": [
          "2"
        ],
        "quantityMatched": 1
      },
      {
        "isMatched": false,
        "term": "Cora",
        "itemsMatched": [],
        "quantityMatched": 0
      }
    ],
    "itemsMatched": [
      "3",
      "1"
    ],
    "quantityMatched": 2,
    "isMatched": true
  },
  "dateRule": {
    "min": "2019-01-01",
    "max": "2019-11-01",
    "isMatched": true
  },
  "priceRule": {
    "eligibleOnly": 15,
    "totalAmount": null,
    "isMatched": false
  },
  "signRule": {
    "signList": [
      "Cora",
      "Auchan",
      "Carrefour"
    ],
    "isMatched": true
  },
  "allRulesMatched": false,
  "totalPriceOfMatchedItems": 9.74
}

How to select terms for itemRule

This is the key step to a successful promotion campaign. The heart of any campaign is the terms that should be validated in a receipt that correspond to eligible products.

How our algorithm works

  • All words of a term should be present

Our algorithm requires all words in a term to be found in the label for it to be validated. Thus, if the term is Nestle Fitness Bio Cereales, then all 4 words should be present in the label exactly the way they are written.

Label in receiptValidation resultWords foundExplanation
Fitness BioNo match 🚫2 words out of 4
Fitn Bio CerNo match 🚫1 word out of 4abbreviations are not matched
  • The order of words in a term does not matter -> Bio Fitness is equivalent to Fitness Bio
  • Alternative names are not considered/created by default. They should be present as another term.

KLGS written in a receipt will not match term Kelloggs, you have to add the term KLGS.

👍 Good practices

Here are some good practices to be implemented when creating terms for a promotion campaign.

What to include:

  • Entire name of the main brand: Kellogg

TIP

Without the apostrophe and s at the end

  • Possible abbreviations of the main brand: KLGS
  • If there is a brandline with a rather unique name (confusion with another product is not likely), add only the name of the brand line.
json
{
  "itemRule": {
    "or": [
      {
        "term": "Kellogg"
      },
      {
        "term": "KLGS"
      }
    ]
  }
}

Brandline

A brandline is a rather narrow line of products that belongs to a parent brand.

Opt for a brandline if its name is unique enough:

Actimel instead of Danone Actimel,

Fitness instead of Nestle Fitness

TIP

Add only necessary words.

Imagine you want all Tresor cereals, and you know that they exist with different taste:

  • Tresor Dark
  • Tresor choco
  • Tresor white

Then add only necessary words for products to distinguish them from the same brand line. In other words, if you want all Tresor cereals just add:

json
{
  "itemRule": {
    "or": [
      {
        "term": "Kellogg"
      },
      {
        "term": "KLGS"
      },
      {
        "term": "Tresor"
      }
    ]
  }
}

If you want only a specific taste of Tresor cereals then do:

json
{
  "itemRule": {
    "or": [
      {
        "term": "Kellogg"
      },
      {
        "term": "KLGS"
      },
      {
        "term": "Tresor Dark"
      }
    ]
  }
}

WARNING

Be careful when adding some general terms without a brand : Yaourt nature will match all natural flavoured yogurts without any brand consideration.

What to avoid

Term of itemRule✅ Do🚫 Don'tExplanation
Do not use plural forms✅ Thé vert🚫 Thés verts
Avoid duplicates✅ Activia🚫 Activia Natureall labels with the term activia (nature or not) are already matched by the first term
Avoid one-letter words in term✅ carte noire🚫 c noireany word with the letter c will match like chaussette noire
Avoid 4 words and longer terms✅ Grand Mere Espresso🚫 Grand Mere Espresso Coffee

Special cases

Don't add the product's nature (or essence) like bread, coffee, yogurt. Only include these words if no brand is present OR if the brand covers several groups of product.

For example the brand Président makes cheese and cream, and you only want cream: then put president creme. But if you only want the cheese put Président only. Because the main activity of Président is cheese, you will likely have only PRESIDENT in the receipt if it's cheese.

What to exclude

DANGER

Try to avoid special characters, articles and any other short words that are not unique to an item and can be omitted in a receipt line due to its limited length.

Here is a possible list of words to exclude:

  • Any special characters (hyphen -, colon, &, apostrophe): use a space instead.
  • No accents: é è à â...
  • Articles : the, a, an
  • Prepositions and Conjunctions: of, with, and, or, but...
  • Pronouns : I, me, he, she, this, that, these, those
  • Quantifiers and Numbers : one, thirty, much, many, some, any, enough, all, both, half
  • Determiners: other, another, such, what, rather, quite
Bad TermReason
Les deux vaches \- yaourts naturearticle, plural forms, hyphen, too many words
Pim's Biscuits Lu à l'orangeapostrophe, article and preposition, parent brand Lu and brandline at the same time (Pims is enough), too precise (à l'orange)
Caféaccent, too short and generic

Step-by-step guide

Let's consider a campaign as an example.

The products concerned by this campaign will be toast bread ("pain de mie") of the brandline American Sandwich from the parent brand Harry's.

1. Brand or Brandline:

The easiest term would be the brandline itself american sandwich.

2. Abbreviations:

The most common abbreviation of this brandline is ams. It is unique enough to be added as a term although it's a rather short word. If you are doubting that it could validate false-positive items, you can specify the term like so: ams pain or/and ams mie or/and harry ams.

Some shorten abbreviations also can be useful: am sand.

TIP

Keep the complete term american sandwich as it can be matched with a detected brand of an item.

3. Combinations of Brand + Product's Nature:

Sometimes american sandwich is omitted and the desired item can be described as bread of brand Harry's.

Let's develop this possibility:

  • harry pain instead of harry's pain de mie
  • harry mie instead of harry's pain de mie
  • 100% mie: it's a unique product of brand Harry's so can it be used without the parent brand

TIP

Notice that we removed 's from harry's - the unique name of the brand is still preserved.

4. Abbreviations + Product's characteristics

When using abbreviations (especially short ones), a characteristic of a product can be added: ams nat (nat for nature).

Finally, the possible list of terms for such a campaign would be:

  • american sandwich
  • ams pain
  • ams mie
  • ams nat
  • harry ams
  • harry mie
  • harry pain
  • 100% mie
  • am sand

The rules JSON should look like this:

json
{
  "itemRule": {
    "or": [
      {
        "term": "am sand"
      },
      {
        "term": "100% mie"
      },
      {
        "term": "harry pain"
      },
      {
        "term": "harry mie"
      },
      {
        "term": "harry ams"
      },
      {
        "term": "ams nat"
      },
      {
        "term": "american sandwich"
      }
    ]
  }
}