Discount Campaigns

The Discount Campaign Import Endpoint

https://{BASE_URL}/imports/discount_campaigns

All import integration endpoints use the same authentication parameters, please see Authentication page for more details.

Advanced Discount Campaign Import Parameters

When importing Discount Campaigns you can additionally specify which Markets and Channels you wish to import for. The default market is dk (Denmark) and the default channel is pos - signifying the POS channel for all Shops in the Danish market.

These defaults can be overridden by the query parameters markets and channels respectively. The value for both parameters are comma separated lists of markets and channels.

E.g.:

https://{BASE_URL}/imports/discount_campaigns?markets=dk,se,no&channels=pos,online&...

For further clarification of the Market and Channel concepts, please read the Vocabulary.

Importing Discount Campaigns

Send a POST request to the endpoint with the parameters specified above.

The body of the POST request must be a JSON object with the following layout:

{
    "campaigns": {
        [campaign A],
        [campaign B],
        ...
    }
}

The definition of the Discount Campaign models can be found in the Models document. Here is an example with mixed discount campaign types:

{
    "campaigns": [
        {
            "id": "0001",
            "type": "percentage_discount-count_or_more-single_product",
            "product_id": "jumper",
            "percentage": 0.42,
            "name": "Jumper discount week 42",
            "display_name": "Jumper Discount",
            "count": 3,
            "priority": 40
        },
        {
            "id": "0002",
            "type": "percentage_discount-tag",
            "tag": "clothing",
            "percentage": 0.42,
            "name": "Clothes discount",
            "display_name": "Clothes discount",
            "priority": 60
        },
        {
            "id": "0003",
            "type": "new_price_discount-single_product",
            "product_id": "pants-501",
            "new_price_per_item": {"dk": 42, "no": 60},
            "name": "Pants sale week 42",
            "display_name": "New price discount",
            "priority": 80
        },
        {
            "id": "0004",
            "type": "percentage_discount-count_or_more-multiple_products",
            "product_ids": ["jumper", "pants"],
            "percentage": 0.5,
            "name": "Pants and jumpers half price week 42",
            "display_name": "Buy three half price",
            "count": 3,
            "priority": 40
        },
        {
            "id": "0005",
            "type": "new_price_discount-count_or_more-single_product",
            "product_id": "glove-one-size",
            "new_price_per_item": 42,
            "name": "New price discount",
            "display_name": "New price discount",
            "priority": 80,
            "count" : 2
        },
        {
            "id": "0006",
            "type": "percentage_discount-stair-single_product",
            "display_name" : "Discount",
            "name" : "Prgoressive zinfandel discount",
            "priority" : 40,
            "product_id" : "zinfandel",
            "steps" : [ {
                "count" : 3,
                "percentage" : 0.1
            }, {
                "count" : 6,
                "percentage" : 0.15
            }, {
                "count" : 9,
                "percentage" : 0.2
            } ]
        },
        {
            "id" : "0007",
            "type": "new_price_discount-stair-single_product",
            "continue_evaluation" : true,
            "display_name" : "Discount",
            "name" : "Progressive nail discount",
            "priority" : 50,
            "product_id" : "9-inch-nail",
            "steps" : [ {
                "count" : 3,
                "new_price_per_item" : {
                    "dk" : 100,
                    "norge" : 150
                }
            }, {
                "count" : 6,
                "new_price_per_item" : {
                    "dk" : 90,
                    "norge" : 130
              }
            }, {
                "count" : 9,
                "new_price_per_item" : {
                    "dk" : 80,
                    "norge" : 110
              }
            } ]
        },
        {
            "id" : "0008",
            "type": "percentage_discount-stair-tag",
            "display_name" : "Discount",
            "members_only" : true,
            "name" : "Progressive discount on all red wines",
            "priority" : 10,
            "steps" : [ {
                "count" : 3,
                "percentage" : 0.1
            }, {
                "count" : 6,
                "percentage" : 0.15
            }, {
                "count" : 9,
                "percentage" : 0.2
            } ],
            "tag" : "red-wine"
        },
        {
            "id" : "0009",
            "type": "percentage_discount-count_or_more-tag",
            "count" : 3,
            "display_name" : "Discount",
            "name" : "Percentage discount for all red wines at 3 or more",
            "percentage" : 0.1,
            "priority" : 2,
            "tag" : "red-wine"
        },
        {
            "id": "0010",
            "type": "new_price_discount-single_product",
            "product_id": "10-m-cable",
            "new_price_per_item_if_cheaper": {"dk": 42, "no": 60},
            "name": "10 m cables price if cheaper than normal price",
            "display_name": "Special price",
            "priority": 80
        },
        {
            "id": "0011",
            "type": "new_price_discount-count_or_more-single_product",
            "product_id": "10-m-cable",
            "new_price_per_item_if_cheaper": 42,
            "name": "10 m cables price if cheaper than normal price at 2 or more",
            "display_name": "Special price",
            "priority": 80,
            "count" : 2
        },
        {
            "id" : "0012",
            "type": "new_price_discount-stair-single_product",
            "continue_evaluation" : true,
            "display_name" : "Special price",
            "name" : "Progressive 10 m cables price if cheaper than normal price",
            "priority" : 50,
            "product_id" : "10-m-cable",
            "steps" : [ {
                "count" : 3,
                "new_price_per_item_if_cheaper" : {
                    "dk" : 100,
                    "norge" : 150
                }
            }, {
                "count" : 6,
                "new_price_per_item_if_cheaper" : {
                    "dk" : 90,
                    "norge" : 130
                }
            }, {
                "count" : 9,
                "new_price_per_item_if_cheaper" : {
                    "dk" : 80,
                    "norge" : 110
                }
            } ]
        }
    ]
}

NOTE

When discount campaigns are imported into the Ka-ching system, the id will be used as a unique key.

One limitation in the database we are using (the Firebase real-time database) is that not all characters are valid to use in keys.

This means that the following list of characters may not be used in the "id" field of a product: ., /, #, $, [ and ]

Campaign Types: Percentage by condition on count

If you wish to give a discount to one or more products based on the presence of a specific count (or more) of a product you can use the types percentage_discount-count_or_more-single_product and percentage_discount-count_or_more-multiple_products:

{
    "campaigns": [
        {
            "id": "0001",
            "type": "percentage_discount-count_or_more-single_product",
            "product_id": "abc",
            "percentage": 0.42,
            "name": "ABC discount",
            "display_name": "Discount",
            "count": 3,
            "priority": 40
        }
    ]
}

This will give a 42% discount on the product with id abc if there are 3 or more of these in the basket.

{
    "campaigns": [
        {
            "id": "0001",
            "type": "percentage_discount-count_or_more-multiple_products",
            "product_ids": ["abc", "def"],
            "percentage": 0.42,
            "name": "ABC discount",
            "display_name": "Discount",
            "count": 3,
            "priority": 40
        }
    ]
}

This will give a 42% discount on the products with either id abc or def if there are 3 or more of these in the basket in total. This will then trigger if there is 1 * abc and 2 * def.

Campaign Types: Percentage by presence of tag

{
    "campaigns": [
        {
            "id": "0002",
            "type": "percentage_discount-tag",
            "tag": "clothing",
            "percentage": 0.42,
            "name": "Clothes discount",
            "display_name": "Clothes discount",
            "priority": 60
        }
    ]
}

This will give a 42% discount unconditionally for products that contain the tag clothing.

Campaign Types: Percentage by presence of tag with condition on count

{
    "campaigns": [
        {
            "id": "0003",
            "type": "percentage_discount-count_or_more-tag",
            "tag": "clothing",
            "percentage": 0.42,
            "name": "Clothes discount",
            "display_name": "Clothes discount",
            "count": 3,
            "priority": 80
        }
    ]
}

This will give a 42% discount for products that contain the tag clothing but only if there are 3 or more items with that tag.

Campaign Types: New price by product

{
    "campaigns": [
        {
            "id": "0003",
            "type": "new_price_discount-single_product",
            "product_id": "abc",
            "new_price_per_item": 42,
            "name": "New price discount",
            "display_name": "New price discount",
            "priority": 80
        }
    ]
}

This will give a 'new price' discount unconditionally for the product with id 'abc'. This is similar to modelling a sale price directly on the product.

Campaign Types: New price by product with condition on count

{
    "campaigns": [
        {
            "id": "0003",
            "type": "new_price_discount-count_or_more-single_product",
            "product_id": "abc",
            "new_price_per_item": 42,
            "name": "New price discount",
            "display_name": "New price discount",
            "count": 3,
            "priority": 80
        }
    ]
}

This will give a 'new price' discount for the product with id 'abc', but only if there are 3 or more items that id.

Campaign Types: New price 'stair' for a single product

{
    "campaigns": [
        {
            "id": "0003",
            "type": "new_price_discount-stair-single_product",
            "product_id": "abc",
            "name": "Price stair",
            "display_name": "Price stair",
            "steps": [
                { "count": 3, "new_price_per_item": 100 },
                { "count": 6, "new_price_per_item": 90 },
                { "count": 9, "new_price_per_item": 80 }
                ],
            "priority": 80
        }
    ]
}

This will create a 'new price' stair for the product with id 'abc'. This means that for 1 or 2 items, the price will be the default. For 3-5 or more it will be 100, for 6-8 it will be 90 and for 9 or more it will be 80.

Campaign Types: Percentage discount 'stair' for a single product

{
    "campaigns": [
        {
            "id": "0003",
            "type": "percentage_discount-stair-single_product",
            "product_id": "abc",
            "name": "Percentage stair",
            "display_name": "Percentage stair",
            "steps": [
                { "count": 3, "percentage": 0.1 },
                { "count": 6, "percentage": 0.15 },
                { "count": 9, "percentage": 0.2  }
                ],
            "priority": 80
        }
    ]
}

This will create a 'percentage' stair for the product with id 'abc'. This means that for 1 or 2 items, the price will be the default. For 3-5 or more it will be discounted with 10%, for 6-8 it will be discounted with 15% and for 9 or more it will be discounted with 20%.

Campaign Types: Percentage discount 'stair' for a products matching a certain tag

{
    "campaigns": [
        {
            "id": "0003",
            "type": "percentage_discount-stair-tag",
            "tag": "clothing",
            "name": "Percentage stair",
            "display_name": "Percentage stair",
            "steps": [
                { "count": 3, "percentage": 0.1 },
                { "count": 6, "percentage": 0.15 },
                { "count": 9, "percentage": 0.2  }
                ],
            "priority": 80
        }
    ]
}

This will create a 'percentage' stair for the products matching the tag 'clothing'. This means that for 1 or 2 items, the price will be the default. For 3-5 or more it will be discounted with 10%, for 6-8 it will be discounted with 15% and for 9 or more it will be discounted with 20%.

Only applying 'new price' if it is cheaper than the original price

Example:

{
    "campaigns": [
        {
            "id": "0010",
            "type": "new_price_discount-single_product",
            "product_id": "10-m-cable",
            "new_price_per_item_if_cheaper": {"dk": 42, "no": 60},
            "name": "10 m cables price if cheaper than normal price",
            "display_name": "Special price",
            "priority": 80
        }
    ]
}

This will give a 'new price' discount only if the new price for the particular product is less than the calculated price in the basket.

This is useful if you for example have different purchase types fx. "Member prices" and those prices are cheaper than the default prices with this discount applied. Using the "if cheaper" discount only applies the new price if it's cheaper than what's already calculated at that point in the basket.

To use this, just specify the key new_price_per_item_if_cheaper instead of new_price_per_item.

This is available for all the 'new price' discount rules: new_price_discount-single_product, new_price_discount-count_or_more-single_product" and new_price_discount-stair-single_product

Discount Campaigns across multiple markets

When using this type of campaign across different markets, it becomes necessary to specify the new price in each of the markets. This can be done as follows:

{
    "campaigns": [
        {
            "id": "0003",
            "type": "new_price_discount-single_product",
            "product_id": "abc",
            "new_price_per_item": { "dk": 42, "no": 60 },
            "name": "New price discount",
            "display_name": "New price discount",
            "priority": 80
        }
    ]
}

A discount stair could look as follows in multiple markets:

{
    "campaigns": [
         {
            "id": "0002",
            "type": "new_price_discount-stair-single_product",
            "product_id": "abc",
            "name": "ABC discount",
            "display_name": "Discount",
            "steps": [
                { "count": 3, "new_price_per_item": { "dk": 100, "norge": 150 } },
                { "count": 6, "new_price_per_item": { "dk": 90, "norge": 130 } },
                { "count": 9, "new_price_per_item": { "dk": 80, "norge": 110 }  }
                ],
            "priority": 50
        }
    ]
}

Creating 'member only' discounts

For any discount campaign template, you may specify 'members only' on the template. The interpretation of this field is that the discount will only apply if there is a customer attached to the current sale.

{
    "campaigns": [
          {
            "id": "0003",
            "type": "percentage_discount-stair-tag",
            "tag": "vin",
            "name": "Member discount",
            "members_only": true,
            "display_name": "Member discount",
            "steps": [
                { "count": 3, "percentage": 0.1 },
                { "count": 6, "percentage": 0.15 },
                { "count": 9, "percentage": 0.2  }
                ],
            "priority": 10
        }
    ]
}

The discount stair above will only apply when a customer is present on the sale.

Allowing multiple discounts on the same item

For any discount campaign template, you may specify 'continue evaluation' on the template. The interpretation of this field is that even after applying this specific discount, the same item can receive other discounts as well.

{
    "campaigns": [
        {
            "id": "0003",
            "type": "new_price_discount-single_product",
            "product_id": "merlot",
            "new_price_per_item": 100,
            "name": "New price discount",
            "display_name": "New price discount",
            "members_only": true,
            "continue_evaluation": true,
            "priority": 80
        },
        {
            "id": "0004",
            "type": "percentage_discount-stair-tag",
            "tag": "wine",
            "name": "Percentage discount",
            "display_name": "Percentage discount",
            "steps": [
                { "count": 3, "percentage": 0.1 },
                { "count": 6, "percentage": 0.15 },
                { "count": 9, "percentage": 0.2  }
                ],
            "priority": 10
        }
    ]
}

Imagine that you sell a bottle of wine with the product id: "merlot". The product is tagged with "wine" and it costs 150 DKK.

The first discount (0003) will only trigger for members and will reduce the price to 100 per bottle. If you buy 6 of these, you will furthermore get a discount (from discount 0004) of 15% on top of the discountet price.

The total will be (100 * 6) * (1 - 0.15) = 510 DKK (85 DKK per bottle)

Deleting Discount Campaigns

Send an HTTP DELETE request to the endpoint with a body containing a JSON array of Discount Campaign ids.

[
  "0001", "0003"
]