Skip to main content

Promotions

Promotions generally consist of three main segments:

  1. General info
  2. Conditions
  3. Action

A promotion can have one or more Conditions that need to be fulfilled before it can be applied. These Conditions can relate to orders, products, users and much more.

The Action determines the effect your promotion will have. A promotion can only have one Action. Actions can vary from free products to percentage discounts on order or line level.

General info​

{
  "Description": "Simple 10% discount",
  "MarketingDescription": "This is a discount in its most basic shape and form.",
  "BackendID": "discount_backendid",
  "CampaignID": 48,
  "CurrencyID": "GBP",
  "LayerID": 1,
  "OrganizationUnitSetID": 16,
  "StartDate": "2021-11-21T23:00:00.000Z",
  "EndDate": "2021-12-30T23:00:00.000Z",
  "DiscountOrderType": 1,
  "ApplyTo": 0,
  "MaximumUsagePerOrder": 1,
  "MaximumUsage": 10,
  "UserUsageLimit": 1,
  "UserUsageReloadStrategy": "quarterly",
  "LedgerClassID": "",
  "CouponHandler": "DEFAULT",
  "Trigger": 0,
  "IsActive": true,
  "CouponsGeneratedByOtherDiscount": false,
  ...
}

Conditions​

V2:STOCKLABEL
{
  "Conditions": [
    {
      "Data": {
        "UseRequestedDateOnOriginatingOrder": false,
        "OriginatingOrderProductsToDetermineRequestedDate": {
        "PRODUCTSET"
        },
        "UseFurthestDate": false,
        "UsableAfterXDays": 0,
        "DaysValid": 0,
        "UsableFrom": "01-01-2020 12:00",
        "UsableTill": "01-01-2020 16:00"
      },
      "Type": "V2:COUPONVALIDITY",
      "UseAsActionCondition": false
    }
  ],
  "ConditionType":1
}
V2:PRODUCT
{
  ...
    "Conditions":[
    {
      "Data":{
        "IgnoreProductsWithOriginalPrice":true,
        "UsageType":1,
        "IdenticalProductsOnly":true,
        "Products":[
          {
            "Name":"test",
            "IsDiscountableProductSet":false,
            "RequiredQuantityOfProducts":3,
            "DiscountableQuantityOfProducts":null,
            "Filters":[
              {
                "PropertyName":"custom_id",
                "Values":[
                  "108-111-978020137940"
                ],
                "ExactMatch":true,
                "Exclude":false
              }
            ]
          }
        ]
      },
      "Type":"V2:PRODUCT",
      "UseAsActionCondition":false
    }
  ],
  "ConditionType":1
}
V2:CUSTOMERAGE
{
  ...
  "Conditions":[
    {
      "Data":{
        "MinimumAge":16,
        "MaximumAge":100,
        "ExactAgeOnly":false
      },
      "Type":"V2:CUSTOMERAGE",
      "UseAsActionCondition":false
    }
  ],
  "ConditionType":1
}
V2:USERROLE
{
  ...
  "Conditions":[
    {
      "Data":{
        "UserRoleIDs":[
          1
        ],
        "IsExcludingCondition":true,
        "ValidateOnCustomer":true
      },
      "Type":"V2:USERROLE",
      "UseAsActionCondition":false
    }
  ],
  "ConditionType":1
}
V2:USERTYPE
//The UserType condition is only available for manual discounts

{
  ...
  "Conditions":[
    {
      "Data":{
        "UserTypes":1,
        "IsExcluding":false
      },
      "Type":"V2:USERTYPE",
      "UseAsActionCondition":false
    }
  ],
  "ConditionType":1
}
V2:ORDERAMOUNT
{
  ...
  "Conditions":[
    {
      "Type":"V2:ORDERAMOUNT",
      "UseAsActionCondition":false,
      "Data":{
        "MinimumAmount":10,
        "MaximumAmount":100,
        "IgnoreProductsWithOriginalPrice":false,
        "ExcludedProducts":[

        ]
      }
    }
  ],
  "ConditionType":1
}
V2:USERCUSTOMFIELD
{
  ...
  "Conditions":[
    {
      "Data":{
        "Type":1,
        "Conditions":[
          {
            "CustomFieldId":1,
            "CustomFieldValue":"NewBlack"
          },
          {
            "CustomFieldId":1,
            "CustomFieldValue":"Adyen"
          }
        ]
      },
      "Type":"V2:USERCUSTOMFIELD"
    }
  ],
  "ConditionType":1
}
Note

ConditionType specifies whether only one condition needs to apply, or all of them."

Actions​

V2:CUSTOMFIELDVALUEDETERMINEDDISCOUNT
{
  "ActionData":{
    "FinancialDispersion":0,
    "CustomFieldID":1,
    "CustomFieldValueUsage":0,
    "LookupList":[
        {
        "CustomFieldValue":{},
        "DiscountValue":10.11
        },
        {
        "CustomFieldValue":{},
        "DiscountValue":10.11
        }
    ],
    "DiscountValueUsage":0,
    "MaxDiscountValue":0
    },
  "ActionType":"V2:CUSTOMFIELDVALUEDETERMINEDDISCOUNT"
}

// CustomFieldValueUsage can be used to determine the way the value in the userfield is used. 
// - AsDiscountValue (0) indicates that the value that is in the custom field must be used as the discount value itself. When the value isn’t a numeric type, no value can be determined and no discount will be given.
// - AsLookupValue (1) indicates that the value of the custom field must be used as a lookup for the LookupList. If the value can not be found in the ValueList, not value can be determined and no discount will be given.

// LookupList is a lookup list which connects a custom field value to a discount value. 
// The CustomFieldValue must be a JToken. 
// DiscountValue must be a numerical value (e.g. int, decimal). 
// When CustomFieldValueUsage is set to AsDiscountValue (0), this list will be ignored (and not stored!). 
// When CustomFieldValueUsage is set to AsLookupValue (1), this list is required and required at least 2 entries.
V2:DISCOUNTPERCENTAGE
{
  ...
  "ActionType": "V2:DISCOUNTPERCENTAGE",
  "ActionData": {
    "Percentage": 10,
    "FinancialDispersion": 0
  }
}

Creating discounts​

CreateDiscount
{
  "Description":"Simple 10% discount",
  "MarketingDescription":"This is a discount in its most basic shape and form.",
  "BackendID":"discount_backendid",
  "CampaignID":48,
  "CurrencyID":"GBP",
  "LayerID":1,
  "OrganizationUnitSetID":16,
  "StartDate":"2021-11-21T23:00:00.000Z",
  "EndDate":"2021-12-30T23:00:00.000Z",
  "DiscountOrderType":1,
  "ApplyTo":0,
  "MaximumUsagePerOrder":1,
  "MaximumUsage":10,
  "UserUsageLimit":1,
  "UserUsageReloadStrategy":"quarterly",
  "LedgerClassID":"",
  "CouponHandler":"DEFAULT",
  "Trigger":0,
  "IsActive":true,
  "Conditions":[
    {
      "Data":{
        "MinimumAmount":10,
        "MaximumAmount":100,
        "IgnoreProductsWithOriginalPrice":false,
        "ExcludedProducts":[
          
        ]
      },
      "Type":"V2:ORDERAMOUNT",
      "UseAsActionCondition":false
    }
  ],
  "ConditionType":1,
  "ActionType":"V2:DISCOUNTPERCENTAGE",
  "ActionData":{
    "Percentage":10,
    "FinancialDispersion":0
  }
}

Orderlevel discount distribution​

For sales reporting purposes, a service called GetOrderDiscountInfo can be used where discounts applied are presented on OrderLine i.e. the service returns the applied discount and the respective impacted order line.

Here is how it would look like: 

{
    "OrderID": 289
}