Search

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 nameDescriptionPossible valueRequired
campaignIDLeave this field empty when creating a new promotion.Integer
startDatePromotion start date.Date
endDatePromotion end date.Date
namePromotion 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
nameENGString
nameSPAString
nameGERString
nameSWEString
nameFINString
nameRUSString
nameESTString
nameLATString
nameLITString
nameGREString
typeDescribes 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.
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)
subsidyAvailable only if Price list row subsidy and other fields module is enabled on your account.

Subsidy must be a non-negative decimal.
Decimal
subsidyValueDEPRECATED — 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
subsidyTypeIDAvailable only if Price list row subsidy and other fields module is enabled on your account.Integer
pageAvailable only if Price list row subsidy and other fields module is enabled on your account.

Page must be a non-negative integer.
Integer
positionOnPageAvailable 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
forecastUnitsAvailable 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 will not contain two or more requirements simultaneously.

If the specified condition is met, customer becomes eligible for the promotional offer.
purchaseTotalValueDecimal
purchasedProductGroupIDInteger
purchasedProductCategoryIDInteger
purchasedProductsA comma-separated list of purchased products.String
purchasedAmountInteger
rewardPointsInteger
priceAtLeastOptional, 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
priceAtMostOptional, 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. 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.
. A promotion rule will not contain two or more awards simultaneously.
percentageOffEntirePurchaseThis 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
percentageOffIncludedProductsArray

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
sumOffEntirePurchaseDecimal
sumOffExcludedProductsA comma-separated list of products.String
sumOffIncludedProductsA comma-separated list of products.String
specialPriceDecimal
awardedAmountIn 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
awardedProductGroupIDInteger
awardedProductCategoryIDInteger
awardedProductsA comma-separated list of awarded products.String
excludedProductsA comma-separated list of excluded products.String
lowestPriceItemIsAwarded0 or 1Integer
percentageOFFDecimal
discountForOneLineDecimal
sumOFFDecimal
percentageOffMatchingItemsInteger
sumOffMatchingItemsDecimal
maximumPointsDiscountThis 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
customerCanUseOnlyOnceInteger (0 or 1)
requiresManagerOverrideSet 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)
reasonIDReason Code ID. A reason code can be associated with a promotion only when its purpose has been set to "PROMOTION".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 nameTypeDescription
campaignIDIntegerID of the created/updated item.
nonExistentStoreRegionIDsString (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.
nonExistentCustomerGroupIDsString (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.