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
tierID Promotion tier ID. Use 0 to remove tier. Tiers specify order of promotion applying and ability to disable promotions with manual discount reason codes. 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 list of product groups (purchasedProductGroupIDs)

  3. The customer must buy at least a certain number of items (purchasedAmount) from a list of product categories (purchasedProductCategoryIDs)

  4. The customer must buy at least a certain number of items (purchasedAmount) from a list of brands (purchasedBrandIDs)

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

  6. 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 Do not use this field; it is only kept for compatibility. Use "purchasedProductGroupIDs" instead. It is possible to specify multiple product groups. Integer
purchasedProductCategoryID Do not use this field; it is only kept for compatibility. Use "purchasedProductCategoryIDs" instead. It is possible to specify multiple product categories. Integer
purchasedProductGroupIDs A comma-separated list of purchased product group IDs. String
purchasedProductCategoryIDs A comma-separated list of purchased product caregory IDs. String
purchasedBrandIDs A comma-separated list of purchased brand IDs. String
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 purchased items (purchasedAmount pcs of purchasedProducts) for a special bundle 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 list of product groups (awardedProductGroupIDs)
    2. from a list of product categories (awardedProductCategoryIDs)
    3. from a list of brands (awardedBrandIDs)
    4. from a list of products (awardedProducts)
    5. 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 / purchasedProductGroupIDs / purchasedProductCategoryIDs / purchasedBrandIDs), 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)
excludePromotionItemsFromPercentageOffEntirePurchase

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

Indicates that the promotion should not apply to items that have already received a promotion discount (item-level promotions), or have triggered a promotion.

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 Do not use this field; it is only kept for compatibility. Use "awardedProductGroupIDs" instead. It is possible to specify multiple product groups. Integer
awardedProductCategoryID Do not use this field; it is only kept for compatibility. Use "awardedProductCategoryIDs" instead. It is possible to specify multiple product groups. Integer
awardedProductGroupIDs A comma-separated list of awarded product group IDs. String
awardedProductCategoryIDs A comma-separated list of awarded product category IDs. String
awardedBrandIDs A comma-separated list of awarded brand IDs. String
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
maximumNumberOfMatchingItems Maximum limit how many items get the discount. Field "maximumNumberOfMatchingItems", if specified, must be equal to or larger than "purchasedAmount". Integer
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)
oncePerDay Integer (0 or 1)
isBirthdayPromotion Integer (0 or 1)
oncePerBirthday Can only be used when isBirthdayPromotion is enabled. Integer (0 or 1)
onlyForDiscountedItems The campaign can only be used on items that already have a discount applied. 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.