getAppliedPromotionRecords

Retrieve a list of occurrences where a promotion discount, price list discount or a manual discount has been applied to a retail sale.

This information can be used to build a "discount report", outlining how many times a promotion / price list has been invoked, what items have been purchased with it and what is the total discount that customers have received through each type of discount, each price list and each promotion.

A built-in report providing that information can be found in ERPLY back office, Reports → Sales Promotions.

To start accumulating the data, get access to that back office report, and to be able to use this API call, please contact customer support and ask them to enable "Promotion Report" extra module on your account.

Likewise, to accumulate inforation about price lists and manual discounts as well, not only promotions, please contact customer support and ask them to additionally enable the following modules on your account:

  • "Applied Price Lists" module;
  • "Applied Manual Discount" module.
However, you also need to use Classic back office (not Berlin), and version 4.5.0 or greater.

Promotions, unlike price lists, are only applied to sales made from Berlin POS, Touch POS and Windows POS. Promotions are NOT applied to sales made from back office.

If you want to build a third-party sales integration that also uses promotions / price lists and generates this data, see calculateShoppingCart and saveSalesDocument. The flow is as follows: you need to pass shopping cart contents into API calculateShoppingCart. API will return prices, discounts and tax rates, and will also inform which promotions and/or price lists it applied to each cart item. When the sale gets confirmed, this data should be passed along to API saveSalesDocument.

Discount records are returned in the order in which they applied. Generally, the order is as follows:
  1. Price list discounts\:
  2. Manual discount\:
  3. Promotion discounts.


There is one exception, however\: if promotion "Get these items for a fixed total $x" applies, manual discount gets overwritten by the fixed price, and is re-applied after the promotion. Therefore, manual discount may occur twice on one invoice line — to one part of the line quantity, the manual discount is applied before all promotions, and to another part of the line quantity it is applied after a specific promotion.

Input parameters

Parameter name Description Possible value Required
recordIDs  Retrieve multiple records, IDs separated by commas. Eg. "1,2,3,4,5".  String    
invoiceIDs  Comma-separated list of invoice IDs. Retrieve records associated with multiple invoices.  String    
productIDs  Comma-separated list of product IDs. Retrieve records associated with multiple products.  String    
promotionIDs  Comma-separated list of promotion IDs. Retrieve records associated with multiple promotions.  String    
priceListIDs 

Comma-separated list of price list IDs. Retrieve records associated with multiple price lists.

This field can be used only if the "Applied Price Lists Report" module has been enabled on your account. Otherwise, error code 1028 will be returned.

 
String    
dateFrom  Filter records by date range.  Date (yyyy-mm-dd)    
dateTo    Date (yyyy-mm-dd)    
warehouseID  Invoice location ID.  Integer    
pointOfSaleID  Invoice register ID.  Integer    
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
recordID  Integer    
date  Date  Invoice date.  
warehouseID  Integer  Invoice location ID.  
pointOfSaleID  Integer  Invoice register ID.  
customerID  Integer  Customer ID.  
invoiceCreatorID  Integer  Invoice creator ID.  
attendantID  Integer  Attendant ID.  
productID  Integer  Product ID.  
invoiceID  Integer  Invoice ID.  
rowID  Integer 

Invoice row ID.

Use invoiceID and rowID to match this record to the correct invoice and invoice row in getSalesDocuments.

Note however that row IDs are transient values; they change every time a sales document is re-saved. So do not rely on row IDs for data synchronization.

 
promotionID  Integer 

Promotion ID, if the applied discount was a promotion.

Each returned record is either: 1) promotion discount (if promotionID has a non-zero value); 2) price list discount (if priceListID has a non-zero value; 3) manual discount (if both fields are zero).

 
promotionName  String  Promotion name, if the applied discount was a promotion.  
priceListID  Integer 

Price list ID, if the applied discount was a price list.

 
priceListName  String  Price list name, if the applied discount was a price list.  
totalAmount  Decimal  Total amount of the product on invoice row.  
discountedAmount  Decimal 

Total amount to which the discount applied.

A price list discount always applies to the whole row, and "discountedAmount" is equal to "totalAmount". Other types (manual discount and promotion discount), however, may also apply to individual items within one row, in which case "discountedAmount" is smaller than "totalAmount".

 
priceBeforePromotion  Decimal (4 places)  Unit price immediately before this promotion / price list / manual discount applied. (Note that multiple promotions and/or price lists can apply to one sold item; the discounts typically cumulate).

For US accounts, this is the net price. For other countries, this is the price with VAT.  
totalBeforePromotion  Decimal (4 places)  priceBeforePromotion multiplied by discountedAmount. Note that this is not the same as "line total before the discount" — it's only the total of the items to which the discount applied.  
priceAfterPromotion  Decimal (4 places)  Final unit price immediately AFTER applying the promotion / price list.
For US accounts, this is the net price. For other countries, this is the price with VAT.  
totalAfterPromotion  Decimal (4 places)  priceAfterPromotion multiplied by discountedAmount. Note that this is not the same as "line total after the discount" — it's only the total of the items to which the discount applied.  
promotionReasonCodeID  Integer  Reason code ID associated with this promotion. This field contains a non-zero value only when the discount is promotion discount, and a reason code has been defined for that promotion.  
unitDiscount  Decimal (4 places)  $ discount that the promotion / price list applied to one item.  
totalDiscount  Decimal (4 places)  Total $ discount that promotion / price list gave to invoice line.  
promotionType  String 

"ITEMS" or "INVOICE".

This field is populated only for applied promotions, not applied price lists or manual discounts.

"ITEMS" for line promotions, "INVOICE" for any promotions that applied to the whole document.

 
promotionDiscountValue  Decimal  $ discount that was specified in promotion parameters.

(A promotion can have either promotionDiscountValue or promotionDiscountPercentage, but not both.)  
promotionDiscountPercentage  Decimal  Percentage discount as it was defined in promotion description.  
priceListDiscountType  String 

"PRICE" or "DISCOUNT".

This field is populated only for applied price lists, not applied promotions or manual discounts.

"PRICE" if the price list applied a fixed price, "DISCOUNT" if the price list applied a discount percentage.

 
priceListDiscountPercentage  Decimal  Percentage discount applied by the price list (in case the discount was percentage-based, see previous field).  
manualDiscountPercentage  Decimal  Manual discount percentage — if this discount was a manual discount.  
manualDiscountReasonID  Integer  ID of the reason code for the manual discount, if cashier selected a reason. For a list of reason codes, see getReasonCodes.  
*****  ***** 

The following four fields are related to subsidies. Subsidy is money paid by head office to the store, to cover the store's loss of revenue, due to HQ-mandated pricing (discounts and promotions).

These fields are returned only if the "Price list row subsidy and other fields" module has been enabled on your account. To enable that module, you can contact customer support, but keep in mind that the subsidy logic needs custom integration and is currently not a general solution that would work for all companies.

 
unitItemSubsidy  Decimal 

Amount of item-level subsidy (in euros/dollars) earned by the store — per one item.

Item-level subsidy is the subsidy that is applied to price list prices and item-level promotions (eg. "10% off from Product X").

 
unitTransactionSubsidy  Decimal 

Amount of transaction-level subsidy (in euros/dollars) earned by the store - per one item.

Transaction-level subsidy is the subsidy that is applied to transaction-level promotions (eg. "$5 off entire sale").

 
totalItemSubsidy  Decimal 

Total amount of item-level subsidy (in euros/dollars) earned by the store (unitItemSubsidy multiplied by discountedAmount).

 
totalTransactionSubsidy  Decimal 

Total amount of transaction-level subsidy (in euros/dollars) earned by the store (unitTransactionSubsidy multiplied by discountedAmount).