getCampaigns

Retrieve sales promotions.

This API call will return descriptions of promotion rules, which are generally structured as follows: "Customer must do/buy X and will get Y" (a discount, special price etc.)

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

To create a promotion rule, see saveCampaign.

Input parameters

Parameter name Description Possible value Required
campaignID  Promotion ID. Use to retrieve one specific sales promotion.  Integer    
type  "auto", "manual" or "coupon". See below for a description of each type.  String    
activeToday  Search for promotions which are active today (ie. which do not have any date restrictions, or the date range of which includes today's date).
When additional module Optionally Disable Promotions is enabled, then the promotion has to be "enabled" for it to be active. 
Integer (0 or 1)    
warehouseID 

Warehouse ID. Search for promotions that have been configured to apply in this specific location only.

 
Integer    
storeRegionIDs 

Search for promotions that are associated with this specific region. (This will NOT return promotions that do not have any region restriction, ie. which are configured to apply in all stores.)

A comma-separated list of store region IDs.

Using this field will return error 1028 if "Store regions" and "Promotion regions" modules are not enabled on this account.

 
String (comma-separated list of integers)    
customerGroupIDs 

Search for promotions that are associated with this specific customer group. (This will NOT return promotions that do not have any restrictions by customer group, ie. which are configured to apply to all customer groups.)

A comma-separated list of customer group IDs.

Using this field will return error 1028 if "Promotion regions" module is not enabled on this account.

 
String (comma-separated list of integers)    
searchAttributeName  Search from attribute name. searchAttributeName and searchAttributeValue have to be specified both.  String    
searchAttributeValue  Search from attribute value.  String    
changedSince  Retrieve only items that have been added or modified since the specified timestamp. Use it to keep a local database in sync with ERPLY.  Integer (Unix timestamp)    
recordsOnPage  Number of records API should return. By default 20, at most 100.  Integer    
pageNo  API returns at most recordsOnPage items at a time. To retrive the next recordsOnPage items, send a new request with pageNo incremented by one. By default, API returns "page 1".  Integer    
lang  Retrieve item names in a specific language. If omitted, API will return item names in the default language of your ERPLY account.
Possible values:
  • 'eng' - English
  • 'spa' - Spanish
  • 'ger' - German
  • 'swe' - Swedish
  • 'fin' - Finnish
  • 'rus' - Russian
  • 'est' - Estonian
  • 'lat' - Latvian
  • 'lit' - Lithuanian
  • 'gre' - Greek
 
String    

Response

Field name Type Description
campaignID  Integer    
startDate  Date  Promotion start date.  
endDate  Date  Promotion end date.  
name  String    
type  String (6)  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.
 
warehouseID  Integer 

If this field has a value other than 0, the promotion is available only in a specific store.

"warehouseID", "storeRegions" and "storeGroup" are mutually exclusive: only one restriction is supposed to apply at a time.

 
storeGroup  String 

If this field has a value, the promotion is available only in a specific store group.

"warehouseID", "storeRegions" and "storeGroup" are mutually exclusive: only one restriction is supposed to apply at a time.

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

 
storeRegions  Array 

If this list contains any elements, then promotion is available only in specific store regions.

"warehouseID", "storeRegions" and "storeGroup" are mutually exclusive: only one restriction is supposed to apply at a time.

Each list element contains the following fields:

Field nameTypeDescription
idIntegerStore region ID
 
customerGroups  Array 

If this list contains any elements, then promotion will apply only to these customer groups.

Each list element contains the following fields:

Field nameTypeDescription
idIntegerCustomer group ID
 
canBeAppliedManuallyMultipleTimes  Integer (0 or 1)  Indicates that it is possible to apply this promotion manually multiple times.

This depends on the structure of the promotion. Some kinds of promotions support multiple application; for others it is not supported or it would not make sense. The flag is always 0 for non-manual (automatic or coupon-activated) promotions, for one-time promotions and one-time birthday promotions.  
subsidy  Decimal  Available only if Price list row subsidy and other fields module is enabled on your account.  
subsidyValue  Decimal  DEPRECATED — subsidy is recommended instead. Available only if Price list row subsidy and other fields module is enabled on your account.  
subsidyTypeID  Integer  Available only if Price list row subsidy and other fields module is enabled on your account.  
page  Integer  Available only if Price list row subsidy and other fields module is enabled on your account.  
positionOnPage  Integer  Available only if Price list row subsidy and other fields module is enabled on your account.  
forecastUnits  Integer  Available only if Price list row subsidy and other fields module is enabled on your account.  
***  **  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.  
purchaseTotalValue  Decimal   
purchasedProductGroupID  Integer    
purchasedProductCategoryID  Integer    
purchasedProducts  Array  Each array element contains an integer field "productID". If "Price list row subsidy and other fields" module is enabled on your account, it will additionally contain a decimal field "subsidy".  
purchasedAmount  Integer   
rewardPoints  Integer   
requiredCouponID  Integer  If this field is set, then the promotion rule does not apply automatically, but only when customer hands in a particular coupon.  
requiredCouponCode  String  Code of the abovementioned coupon.  
priceAtLeast  Decimal  If this field more than zero 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.  
priceAtMost  Decimal  If this field more than zero 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.  
requiresManagerOverride  Integer  If set to 1, indicates that this is a manual promotion that can be applied to a sale with store manager's approval only. API client (POS) must implement the approval process itself; it is not enforced by API.  
***  **  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  Decimal  This promotion gives a percentage discount on the entire sale.  
excludeDiscountedFromPercentageOffEntirePurchase  Integer (0 or 1) 

This flag applies to promotions "% off entire sale", so you should inspect it only if percentageOffEntirePurchase contains a non-zero value.

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).

 
percentageOffExcludedProducts  Array  A further restriction for the "% off entire sale" promotion. IDs of products to which the discount percentage should not be applied.  
percentageOffIncludedProducts  Array  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.)  
sumOffEntirePurchase  Decimal   
percentageOffMatchingItems  Integer   
sumOffMatchingItems  Decimal   
sumOffExcludedProducts  Array  Each array element contains an integer productID attribute.  
sumOffIncludedProducts  Array  Each array element contains an integer productID attribute.  
specialPrice  Decimal   
awardedProductGroupID  Integer    
awardedProductCategoryID  Integer    
awardedProducts  Array  Each array element contains an integer field "productID". If "Price list row subsidy and other fields" module is enabled on your account, it will additionally contain a decimal field "subsidy".  
awardedAmount  Integer  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".  
excludedProducts  Array  Each array element contains an integer productID attribute.  
reasonID  Integer  Reason Code ID that is associated with this promotion.  
lowestPriceItemIsAwarded  Integer  0 or 1  
percentageOFF  Decimal    
discountForOneLine  Decimal    
enabled  Integer  Possible values: 0 or 1. Available only if Optionally Disable Promotions module is enabled on your account.  
sumOFF  Decimal    
maximumPointsDiscount  Decimal  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).  
customerCanUseOnlyOnce  Integer  0 or 1  
specialUnitPrice  Decimal  New unit price.  
maxItemsWithSpecialUnitPrice  Integer  Maximum limit how many items can be purchased with this special unit price.  
redemptionLimit  Integer  Maximum limit how many times the promotion can be applied to one sale.  
added  Unix timestamp  Creation time.  
lastModified  Unix timestamp  Last modification time.  
attributes  Array  Additional attributes. Each item looks like this:

Field nameTypeDescription
attributeNameStringAttribute name
attributeTypeStringAttribute type
attributeValueStringAttribute value