Search

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 nameDescriptionPossible valueRequired
campaignIDPromotion ID. Use to retrieve one specific sales promotion.Integer
type"auto", "manual" or "coupon". See below for a description of each type.String
activeTodaySearch for promotions which are active today (ie. which do not have any date restrictions, or the date range of which includes today's date).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)
searchAttributeNameSearch from attribute name. searchAttributeName and searchAttributeValue have to be specified both.String
searchAttributeValueSearch from attribute value.String
changedSinceRetrieve 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)
recordsOnPageNumber of records API should return. By default 20, at most 100.Integer
pageNoAPI 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
langRetrieve 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 nameTypeDescription
campaignIDInteger
startDateDatePromotion start date.
endDateDatePromotion end date.
nameString
typeString (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.
warehouseIDInteger

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.

storeRegionsArray

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
customerGroupsArray

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
canBeAppliedManuallyMultipleTimesInteger (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.
subsidyDecimalAvailable only if Price list row subsidy and other fields module is enabled on your account.
subsidyValueDecimalDEPRECATED — subsidy is recommended instead. Available only if Price list row subsidy and other fields module is enabled on your account.
subsidyTypeIDIntegerAvailable only if Price list row subsidy and other fields module is enabled on your account.
pageIntegerAvailable only if Price list row subsidy and other fields module is enabled on your account.
positionOnPageIntegerAvailable only if Price list row subsidy and other fields module is enabled on your account.
forecastUnitsIntegerAvailable 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.
purchaseTotalValueDecimal
purchasedProductGroupIDInteger
purchasedProductCategoryIDInteger
purchasedProductsArrayEach array element contains an integer productID attribute.
purchasedAmountInteger
rewardPointsInteger
requiredCouponIDIntegerIf this field is set, then the promotion rule does not apply automatically, but only when customer hands in a particular coupon.
requiredCouponCodeStringCode of the abovementioned coupon.
priceAtLeastDecimalIf 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.
priceAtMostDecimalIf 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.
requiresManagerOverrideIntegerIf 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. 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.
percentageOffEntirePurchaseDecimalThis promotion gives a percentage discount on the entire sale.
excludeDiscountedFromPercentageOffEntirePurchaseInteger (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).

percentageOffExcludedProductsArrayA further restriction for the "% off entire sale" promotion. IDs of products to which the discount percentage should not be applied.
percentageOffIncludedProductsArrayA 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.)
sumOffEntirePurchaseDecimal
percentageOffMatchingItemsInteger
sumOffMatchingItemsDecimal
sumOffExcludedProductsArrayEach array element contains an integer productID attribute.
sumOffIncludedProductsArrayEach array element contains an integer productID attribute.
specialPriceDecimal
awardedProductGroupIDInteger
awardedProductCategoryIDInteger
awardedProductsArrayEach array element contains an integer productID attribute.
awardedAmountIntegerIn 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".
excludedProductsArrayEach array element contains an integer productID attribute.
reasonIDIntegerReason Code ID that is associated with this promotion.
lowestPriceItemIsAwardedInteger0 or 1
percentageOFFDecimal
discountForOneLineDecimal
sumOFFDecimal
maximumPointsDiscountDecimalThis 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).
customerCanUseOnlyOnceInteger0 or 1
addedUnix timestampCreation time.
lastModifiedUnix timestampLast modification time.
attributesArrayAdditional attributes. Each item looks like this:

Field nameTypeDescription
attributeNameStringAttribute name
attributeTypeStringAttribute type
attributeValueStringAttribute value