saveCampaign

Create or update a sales promotion.

A sales promotion is a rule that gives a discount when a certain condition is met — and can be configured to apply either automatically or be invoked manually by the cashier in POS.

For specifying unconditional discounts (that do not depend on a certain other item being purchased, or customer's total basket value), you should rather use price lists (see getPriceLists).

To retrieve promotions, see getCampaigns.

For an API call that automatically implements all promotion rules and price lists automatically for you, see calculateShoppingCart.

Input parameters

Parameter name Description Possible value Required
campaignID  Leave this field empty when creating a new promotion.  Integer    
startDate  Promotion start date.  Date    
endDate  Promotion end date.  Date    
enabled  Possible values: 0 or 1. Setting it to 0 disables a promotion. Default value is 1. Available only if Optionally Disable Promotions module is enabled on your account.  Integer    
name  Promotion name. Use either general parameter "name" or one or more of the following parameters if you need to set the names in specific languages. To have multilingual names enabled, please contact our customer support. An error will be returned if you attempt to set a name in a specific language and the multilingual names are not enabled on your account.  String    
nameENG    String    
nameSPA    String    
nameGER    String    
nameSWE    String    
nameFIN    String    
nameRUS    String    
nameEST    String    
nameLAT    String    
nameLIT    String    
nameGRE    String    
type  Describes the way promotion is applied. Possible values:
  • auto - Promotion is applied automatically to all customers, based on rules below. No coupons needed.
  • manual - Cashier selects the promotion manually. (Cashier must have relevant rights - getUserRights must return rightApplyPromotions = 1)
  • coupon - Promotion is applied when user hands in a printed coupon with a serial number.

Default value is "auto". 
String (6)    
warehouseID 

Set this field if you want the promotion to be available only in a specific store.

Fields "warehouseID", "storeGroup" and "storeRegionIDs" are mutually exclusive: only one restriction can be set at a time, otherwise error code 1110 will be returned.

 
Integer    
storeGroup 

Set this field if you want the promotion to be available only in a specific store group.

Fields "warehouseID", "storeGroup" and "storeRegionIDs" are mutually exclusive: only one restriction can be set at a time, otherwise error code 1110 will be returned.

"Store group" is a text field on location form.

 
String    
storeRegionIDs 

A comma-separated list of store region IDs.

Set this field if you want the promotion to be available only in selected store regions. To remove the restriction, set the field to an empty string.

Fields "warehouseID", "storeGroup" and "storeRegionIDs" are mutually exclusive: only one restriction can be set at a time, otherwise error code 1110 will be returned.

Using this field will return error code 1028 if "Store regions" and "Promotion regions" modules are not enabled on this account. If you supply a list containing non-numeric values, error 1016 will be returned.

To get a list of store regions, see getStoreRegions.

 
String (comma-separated list of integers)    
customerGroupIDs 

A comma-separated list of customer group IDs.

Set this field if you want the promotion to be available only for selected customer groups. To remove the restriction, set the field to an empty string.

Using this field will return error code 1028 if "Promotion regions" module is not enabled on this account. If you supply a list containing non-numeric values, error 1016 will be returned.

 
String (comma-separated list of integers)    
subsidy  Available only if Price list row subsidy and other fields module is enabled on your account.

Subsidy must be a non-negative decimal. 
Decimal    
subsidyValue  DEPRECATED — subsidy is recommended instead. Available only if Price list row subsidy and other fields module is enabled on your account.

Subsidy must be a non-negative decimal. 
Decimal    
subsidyTypeID  Available only if Price list row subsidy and other fields module is enabled on your account.  Integer    
page  Available only if Price list row subsidy and other fields module is enabled on your account.

Page must be a non-negative integer. 
Integer    
positionOnPage  Available only if Price list row subsidy and other fields module is enabled on your account.

Position on page must be a non-negative integer. 
Integer    
forecastUnits  Available only if Price list row subsidy and other fields module is enabled on your account.

Forecast units must be a non-negative integer. 
Integer    
***  A promotion may have one of the following requirements:
  1. The customer must make a purchase with a total value of $X.XX (purchaseTotalValue)

  2. The customer must buy at least a certain number of items (purchasedAmount) from a particular product group (purchasedProductGroupID)

  3. The customer must buy at least a certain number of items (purchasedAmount) from a particular product category (purchasedProductCategoryID)

  4. The customer must buy at least a certain number of items (purchasedAmount) from among a list of products (purchasedProducts).

  5. The customer must redeem a specified number of loyalty points (rewardPoints)
A promotion rule must not contain two or more requirements simultaneously.

If the specified condition is met, customer becomes eligible for the promotional offer.  
   
purchaseTotalValue    Decimal    
purchasedProductGroupID    Integer    
purchasedProductCategoryID    Integer    
purchasedProducts  A comma-separated list of purchased products.  String    
purchasedProductSubsidies 

A comma-separated list of subsidy amounts (in euros/dollars) for each of the products specified above.

Subsidy is money paid by the head office to the store, to offset the store's loss of revenue, due to HQ-mandated discounts and promotions.

You can only use this field for promotions "Buy at least X pcs of product Y and get $ / % off each one". This is the promotion that can be defined by setting the fields "purchasedProducts", "purchasedAmount", and one of either "percentageOffMatchingItems" or "sumOffMatchingItems". Since this promotion gives discounts to the same items that customer is required to buy, the subsidies need to be associated with "purchasedProducts". These amounts of subsidy will be paid out when this promotion applies and one of the products listed above (in purchasedProducts) gets a promotional discount.

Attempting to set "purchasedProductSubsidies" for any other type of promotion will return error code 1132.

This comma-separated list must consist of non-negative decimals, and if you set this parameter, the list must be exactly of the same length as "purchasedProducts" (a corresponding subsidy amount for each product ID). For instance:

  • purchasedProducts=1,2,3,4
  • purchasedProductSubsidies=0,0.15,0.35,0
If the lists do not contain the same number of items, error code 1133 will be returned.

This field can be used only if "Price list row subsidy and other fields" module is enabled on your account.

 
String    
purchasedAmount    Integer    
rewardPoints    Integer    
priceAtLeast  Optional, the customer must buy a certain number of items with item price more or equal to this value, doesnt work with total value or reward points. Positive decimal or 0.  Decimal    
priceAtMost  Optional, the customer must buy a certain number of items with item price less or equal to this value, doesnt work with total value or reward points. Positive decimal or 0.  Decimal    
***  A promotion may give one of the following discounts/awards:
  1. The customer gets X% off the entire purchase (percentageOffEntirePurchase)

  2. The customer gets $X.XX off the entire purchase (sumOffEntirePurchase). Note that Erply invoice model does not have a concept of applying a discount sum to the whole invoice. This sum needs to be more-or-less evenly, or proportionally, divided between invoice rows.

  3. The customer gets bought items (purchasedAmount pcs of purchasedProducts) for a specific total price (specialPrice). Such a promotion may be called "Buy Two For $5".

  4. The customer gets a certain sum off (sumOFF), or a discount % off (percentageOFF) of one (awardedAmount = 1), multiple (awardedAmount = n) or infinite (awardedAmount = 0) items:

    1. from a particular product group (awardedProductGroupID)
    2. from a particular product category (awardedProductCategoryID)
    3. from a particular list of products (awardedProducts)
    4. with a price equal to or lower than any items specified above (lowestPriceItemIsAwarded).


  5. The customer gets a % discount on any one chosen receipt line (discountForOneLine)

  6. The customer gets a certain sum (sumOffMatchingItems), or a discount % (percentageOffMatchingItems) off the items that were required for the promotion (purchasedProducts / purchasedProductGroupID / purchasedProductCategoryID), and also of each subsequent similar item.

  7. The customer gets bought items (purchasedAmount pcs of purchasedProducts) for a special discounted price (specialUnitPrice). The promotion can have a maximum limit how many items get the discount(maxItemsWithSpecialUnitPrice).
. A promotion rule will not contain two or more awards simultaneously.  
   
percentageOffEntirePurchase  This promotion gives a percentage discount on the entire sale.  Decimal    
excludeDiscountedFromPercentageOffEntirePurchase 

This flag applies to promotions "% off entire sale", so set it only together with percentageOffEntirePurchase, otherwise API will return error 1129.

Indicates that the promotion should not apply to items that have already received any discount from a price list, a manual discount by the cashier, or a discount from any preceding promotion (both item-level and invoice-level promotions).

By default 0.

 
Integer (0 or 1)    
percentageOffExcludedProducts 

A further restriction for the "% off entire sale" promotion. IDs of products to which the discount percentage should not be applied.

A comma-separated list of product IDs.

 
String    
percentageOffIncludedProducts 

A further restriction for the "% off entire sale" promotion. IDs of the only allowed products to which the discount percentage may be applied, at all. (All other products in the basket should be left unaffected by this promotion.)

A comma-separated list of product IDs.

 
String    
sumOffEntirePurchase    Decimal    
sumOffExcludedProducts  A comma-separated list of products.  String    
sumOffIncludedProducts  A comma-separated list of products.  String    
specialPrice    Decimal    
awardedAmount  In promotion "% or $ off of specific products", how many items should get the discount. Fulfilling the promotion conditions may entitle the customer to one discounted item (awardedAmount = 1), or at most N discounted items (awardedAmount > 1), or an unlimited number of items (awardedAmount = 0). The "unlimited" option may be used in promotions such as "First item costs $3, subsequent ones are $2 each".  Integer    
awardedProductGroupID    Integer    
awardedProductCategoryID    Integer    
awardedProducts  A comma-separated list of awarded products.  String    
awardedProductSubsidies 

A comma-separated list of subsidy amounts (in euros/dollars) for each of the awarded products specified above.

Subsidy is money paid to the store by the head office, to offset the store's loss of revenue, due to HQ-mandated discounts and promotions.

If you specify awardedProductSubsidies, these will be the amounts of subsidy that will be paid out when this promotion applies and one of the products listed above (in awardedProducts) gets a promotional discount.

This comma-separated list must consist of non-negative decimals, and if you set this parameter, the list must be exactly of the same length as "awardedProducts" (a corresponding subsidy amount for each product ID). For instance:

  • awardedProducts=1,2,3,4
  • awardedProductSubsidies=0,0.15,0.35,0
If the lists do not contain the same number of items, error code 1134 will be returned.

This field can be used only if "Price list row subsidy and other fields" module is enabled on your account.

 
String    
excludedProducts  A comma-separated list of excluded products.  String    
lowestPriceItemIsAwarded  0 or 1  Integer    
percentageOFF    Decimal    
discountForOneLine    Decimal    
sumOFF    Decimal    
percentageOffMatchingItems    Integer    
sumOffMatchingItems    Decimal    
maximumPointsDiscount  This setting only applies to promotions that look like "Get $1 of discount for 1 loyalty point". This setting makes sure that regardless of the number of points the customer has, the points can only be exchanged for a limited amount of discount (a specified % of invoice total).  Decimal    
customerCanUseOnlyOnce    Integer (0 or 1)    
requiresManagerOverride  Set to 1 if this is a manual promotion and it should be applied to a sale with store manager's approval only. (If you attempt to set this flag on an automatic or coupon-activated promotion, error 1076 will be returned.)  Integer (0 or 1)    
reasonID  Reason Code ID. A reason code can be associated with a promotion only when its purpose has been set to "PROMOTION".  Integer    
specialUnitPrice  New unit price. Field "specialUnitPrice" must not be specified together with any other award and this field is only allowed together with "purchasedAmount".  Decimal    
maxItemsWithSpecialUnitPrice  Maximum limit how many items can be purchased with this special unit price. Field "maxItemsWithSpecialUnitPrice", if specified, must be equal to or larger than "purchasedAmount".  Integer    
redemptionLimit  Maximum limit how many times the promotion can be applied to one sale. Field "redemptionLimit" is not allowed for promotions that give % off entire invoice, require reward points or apply to an unlimited number of items. Field "redemptionLimit" can only be used together with "maxItemsWithSpecialUnitPrice" (for special unit price promotions).  Integer    
*****  Additional attributes associated with this item.
Attributes must be supplied as a flat list, each attribute defined by the following set of three parameters. Replace # with set number (1, 2, 3, ...). When updating an existing entry, API will only update the attributes specified in input data and leave all other existing attributes unchanged. To delete an attribute, set its value to 'null' or 'undefined'. 
*****    
attributeName#  Attribute name. Name can only contain the following symbols: A-Z, a-z, 0-9, dash and underscore.  String    
attributeType#  Attribute type, possible types are 'text', 'int' and 'double'. By default 'text'.  String    
attributeValue#  Value of the attribute. Set value to 'null' or 'undefined' to delete an attribute.
'text' attribute can be any string, maximum 255 characters.
'int' must be a signed 32-bit integer.
'double' must be a decimal number. 
String    

Response

Field name Type Description
campaignID  Integer  ID of the created/updated item.  
nonExistentStoreRegionIDs  String (comma-separated list of integers)  If you used the input field "storeRegionIDs", this field will contain a comma-separated list of those supplied values that were not valid region IDs.  
nonExistentCustomerGroupIDs  String (comma-separated list of integers)  If you used the input field "customerGroupIDs", this field will contain a comma-separated list of those supplied values that were not valid customer group IDs.  

If you specify a promotion with conflicting or missing rules, API will return one of the following error codes: 1046...1049, 1076, 1110...1119. Refer to the list of error codes for more information.