Search

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 nameDescriptionPossible valueRequired
recordIDsRetrieve multiple records, IDs separated by commas. Eg. "1,2,3,4,5".String
invoiceIDsComma-separated list of invoice IDs. Retrieve records associated with multiple invoices.String
productIDsComma-separated list of product IDs. Retrieve records associated with multiple products.String
promotionIDsComma-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
dateFromFilter records by date range.Date (yyyy-mm-dd)
dateToDate (yyyy-mm-dd)
warehouseIDInvoice location ID.Integer
pointOfSaleIDInvoice register ID.Integer
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
recordIDInteger
dateDateInvoice date.
warehouseIDIntegerInvoice location ID.
pointOfSaleIDIntegerInvoice register ID.
customerIDIntegerCustomer ID.
invoiceCreatorIDInteger Invoice creator ID.
attendantIDIntegerAttendant ID.
productIDIntegerProduct ID.
invoiceIDIntegerInvoice ID.
rowIDInteger

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.

promotionIDInteger

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

promotionNameStringPromotion name, if the applied discount was a promotion.
priceListIDInteger

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

priceListNameStringPrice list name, if the applied discount was a price list.
totalAmountDecimalTotal amount of the product on invoice row.
discountedAmountDecimal

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

priceBeforePromotionDecimal (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.
totalBeforePromotionDecimal (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.
priceAfterPromotionDecimal (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.
totalAfterPromotionDecimal (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.
unitDiscountDecimal (4 places)$ discount that the promotion / price list applied to one item.
totalDiscountDecimal (4 places)Total $ discount that promotion / price list gave to invoice line.
promotionTypeString

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

promotionDiscountValueDecimal$ discount that was specified in promotion parameters.

(A promotion can have either promotionDiscountValue or promotionDiscountPercentage, but not both.)
promotionDiscountPercentageDecimalPercentage discount as it was defined in promotion description.
priceListDiscountTypeString

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

priceListDiscountPercentageDecimalPercentage discount applied by the price list (in case the discount was percentage-based, see previous field).
manualDiscountPercentageDecimalManual discount percentage — if this discount was a manual discount.
manualDiscountReasonIDIntegerID of the reason code for the manual discount, if cashier selected a reason. For a list of reason codes, see getReasonCodes.