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 you wish to import for. The default market is dk (Denmark) - signifying all Shops in the Danish market.
The default can be overridden by the query parameter markets. The value is comma separated lists of markets.
E.g.:
https://{BASE_URL}/imports/discount_campaigns?markets=dk,se,no&...
For further clarification of the Market concept, 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],
...
}
}
Common for all Discount Campaign types are the following properties:
{
"id": "string, required",
"type": "string, required",
"name": "string, required",
"display_name": "string, required",
"priority": number, required
}
id must be a unique identifier for this campaign
type must match one of the supported discount campaign template types that can be seen below
name is the internal name of the campaign
display_name is the name of the discount when applied to a line item in the basket
priority is the priority of the campaign. Campaigns with higher priorities are evaluated before campaigns with lower priorities.
{
"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
idwill 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 discount campaign:
.,/,#,$,*,[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%.
Campaign Types: Amount off discount 'stair' for a products matching a certain tag
{
"campaigns": [
{
"id": "0003",
"type": "amount_discount-stair-tag",
"tag": "clothing",
"name": "Amount off stair",
"display_name": "Amount off stair",
"steps": [
{ "count": 3, "amount_per_item": 10 },
{ "count": 6, "amount_per_item": 15 },
{ "count": 9, "amount_per_item": 20 }
],
"priority": 80
}
]
}
This will create a 'amount off' 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 reduced by 10, for 6-8 it will be reduced by 15 and for 9 or more it will be reduced by 20.
Campaign Types: Free shipping by total amount
{
"campaigns": [
{
"id": "0003",
"type": "free_shipping_by_amount",
"name": "Free shipping",
"display_name": "Free shipping",
"amount_condition": 1000,
"priority": 80
}
]
}
This will create a discount campaign, that will reduce the price of all shipping line items to 0 in case the total (for all line items excluding shipping line items, and after applying all previous discounts) is greater than or equal to 1000,-.
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"
]