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 information 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
changedSince Retrieve only records that have been added or modified since the specified timestamp. 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 retrieve 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 string Format: yyyy-mm-dd. 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.
stableRowID integer Stable ID of the invoice row.
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 number Total amount of the product on invoice row.
discountedAmount number

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 number $ discount that was specified in promotion parameters.

(A promotion can have either promotionDiscountValue or promotionDiscountPercentage, but not both.)
promotionDiscountPercentage number 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 number Percentage discount applied by the price list (in case the discount was percentage-based, see previous field).
manualDiscountPercentage number 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.
unitItemSubsidy number

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

The field is 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.
unitTransactionSubsidy number

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

The field is 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.
totalItemSubsidy number

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

The field is 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.
totalTransactionSubsidy number

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

The field is 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.
added Integer (Unix timestamp) Creation time.
lastModified Integer (Unix timestamp) Last modification time.