Builder API - Discount Types
Make sure you have read the Discount Types guide before reading this guide.
This guide goes into more details of how to use the Builder API to create different types of discounts.
Conditions
Conditions are made up of the following properties:
lineItemGroupCondition- the minimum quantity or spend that the line items need to satisfy.lineItemFilter- the line items to use for this condition.eligibilityExpression- any non line item expression. E.g. customer is VIP.couponGroupId- any coupon codes in evaluation request need to be in the coupon group specified here.
All of these properties are optional. More details on each of these are below.
lineItemGroupCondition
The aggregation of line items need to satisfy this minimum quantity or spend predicate. If a lineItemFilter is supplied, only the line items matching the filter will be considered.
There are 4 types supported:
MinimumQuantityandForEachQuantityMinimumSpendandForEachSpend
An example of a MinimumQuantity condition is below.
{
"name": "Test",
"conditions": [
{
"lineItemGroupCondition": {
"type": "MinimumQuantity",
"quantity": 1
}
}
]
}
An example of a MinimumSpend condition is below.
{
"name": "Test",
"conditions": [
{
"lineItemGroupCondition": {
"type": "MinimumSpend",
"values": [
{
"currencyCode": "GBP",
"value": 100
},
{
"currencyCode": "USD",
"value": 110
},
{
"currencyCode": "EUR",
"value": 110
}
]
}
}
]
}
lineItemFilter
Below is an example that only matches line items with a type of Shirt (a Category property has been setup on the LineItem property).
{
"name": "Test",
"conditions": [
{
"lineItemGroupCondition": {
"type": "MinimumQuantity",
"quantity": 4
},
"lineItemFilter": {
"type": "Group",
"conjunction": "And",
"clauses": [
{
"type": "Property",
"property": "LineItem.Category",
"operator": "equals",
"value": "Shirt"
}
]
}
}
]
}
See the Expressions page for more details on the format.
eligibilityExpression
Below is an example that only matches customers with a segment of VIP (a Segment property has been setup on the Customer property).
{
"name": "Test",
"conditions": [
{
"eligibilityExpression": {
"type": "Group",
"conjunction": "And",
"clauses": [
{
"type": "Property",
"property": "Customer.Segments",
"operator": "contains",
"value": "VIP"
}
]
}
}
]
}
See the Expressions page for more details on the format.
couponGroupId
ID of coupon group required for this discount.
Actions
Amount Off Types
The amountOffType determines the format of the items in the values array on the actions.
AmountOff
This is a currency amount and so supports an entry per currency code.
"values": [
{
"condition": null,
"value": [
{
"currencyCode": "GBP",
"value": 10
},
{
"currencyCode": "USD",
"value": 15
},
{
"currencyCode": "EUR",
"value": 20
}
]
}
]
FixedPrice
This is a currency amount and so supports an entry per currency code.
"values": [
{
"condition": null,
"value": [
{
"currencyCode": "GBP",
"value": 10
},
{
"currencyCode": "USD",
"value": 15
},
{
"currencyCode": "EUR",
"value": 20
}
]
}
]
PercentOff
This is a single value for the percentage.
"values": [
{
"condition": null,
"value": 20
}
]
Tiered Action Values
The condition property allows varying the value by any non line item expression. See Tiered Actions for more details.
The entries in the values array are evaluated in order and once a matching condition is found, the value is used.
The last value should have a null condition so it applies as the default.
See the Expressions page for more details on the format.
Line Item
An example line item action giving 20% off is below. The discount will apply to a maximum of 4 times (2 items per application up to a limit of 2 applications).
{
"name": "Test",
"actions": [
{
"type": "AmountOffLineItem",
"maxItemsPerApplication": 2,
"maxApplications": 2,
"amountOffType": "PercentOff",
"lineItemFilter": null,
"values": [
{
"condition": null,
"value": 20
}
]
}
]
}
lineItemFilter
lineItemFilter allows only applying the action to specific line items.
The full example below only applies the 20% off to line items with a ProductType of "Shirt"
(a ProductType property has been defined on the LineItem property).
{
"name": "Test",
"conditions": [
{
"lineItemGroupCondition": {
"type": "MinimumQuantity",
"quantity": 4
},
"lineItemFilter": {
"type": "Group",
"conjunction": "And",
"clauses": [
{
"type": "Property",
"property": "LineItem.ProductType",
"operator": "equals",
"value": "Shirt"
}
]
}
}
],
"actions": [
{
"type": "AmountOffLineItem",
"maxItemsPerApplication": 1,
"maxApplications": null,
"amountOffType": "PercentOff",
"lineItemFilter": {
"type": "Group",
"conjunction": "And",
"clauses": [
{
"type": "Property",
"property": "LineItem.ProductType",
"operator": "equals",
"value": "Shirt"
}
]
},
"values": [
{
"condition": null,
"value": 20
}
]
}
]
}
Basket
The example below gives 10 GBP, 15 USD, 20 EUR off the basket total.
{
"name": "Test",
"actions": [
{
"type": "AmountOffBasket",
"maxApplications": null,
"amountOffType": "AmountOff",
"values": [
{
"condition": null,
"value": [
{
"currencyCode": "GBP",
"value": 10
},
{
"currencyCode": "USD",
"value": 15
},
{
"currencyCode": "EUR",
"value": 20
}
]
}
]
}
]
}
Costs
Below is an example of 100% off a Shipping cost.
{
"name": "Test",
"actions": [
{
"type": "AmountOffCost",
"name": "Shipping",
"amountOffType": "PercentOff",
"values": [
{
"condition": null,
"value": 100
}
]
}
]
}
Note. Cost names don't need to be predefined in the system. However, you can create a property with the name Costs along with the relevant properties to allow you to add expressions for costs.
Below is the example for a discount that has a condition to ensure it only applies if the Shipping cost hasn't already been discounted. Properties OriginalShipping and Shipping have been created in the property with name Costs.
{
"name": "Test",
"conditions": [
{
"lineItemGroupCondition": {
"type": "MinimumSpend",
"values": [
{
"currencyCode": "GBP",
"value": 30
},
{
"currencyCode": "USD",
"value": 40
},
{
"currencyCode": "EUR",
"value": 50
}
]
},
"eligibilityExpression": {
"type": "Group",
"conjunction": "And",
"clauses": [
{
"type": "PropertyComparison",
"leftProperty": "Costs.OriginalShipping",
"rightProperty": "Costs.Shipping",
"operator": "equals"
}
]
}
}
],
"actions": [
{
"type": "AmountOffCost",
"name": "Shipping",
"amountOffType": "PercentOff",
"values": [
{
"condition": null,
"value": 50
}
]
}
]
}
The Costs property isn't created by default because no cost property names are defined in the system.
Content
An example of a Content based discount is below. This returns a content action if the customer is in the VIP segment (a Segment property has been setup on the Customer property).
{
"name": "Test",
"conditions": [
{
"eligibilityExpression": {
"type": "Group",
"conjunction": "And",
"clauses": [
{
"type": "Property",
"property": "Customer.Segments",
"operator": "contains",
"value": "VIP"
}
]
}
}
],
"actions": [
{
"type": "Content",
"values": [
{
"condition": null,
"value": [
{
"locale": "en-GB",
"value": "Welcome, VIP customer!"
},
{
"locale": "fr-FR",
"value": "Bienvenue, client VIP !"
}
]
}
]
}
]
}
Loyalty
See Loyalty Discount Types for more details.
Display Messages
Below is an example discount with a display message.
{
"name": "Test",
"conditions": [
{
"lineItemGroupCondition": {
"type": "MinimumQuantity",
"quantity": 4
}
}
],
"actions": [
{
"type": "AmountOffLineItem",
"maxItemsPerApplication": 1,
"maxApplications": null,
"amountOffType": "PercentOff",
"lineItemFilter": null,
"values": [
{
"condition": null,
"value": 100
}
],
"displayMessage": {
"values": [
{
"locale": "en-GB",
"value": "Buy 4 get 1 free"
},
{
"locale": "fr-FR",
"value": "Achetez-en 4, obtenez-en 1 gratuit"
}
]
}
}
]
}