Calculate the value of a shopping cart, and have discounts, promotions and taxes automatically calculated by API. You only need to input item IDs and quantities.
calculateShoppingCart is a very versatile function that:
You need to input product IDs and quantities, and you may also specify location ID and customer ID.
calculateShoppingCart can be used in web shops, or to easily implement a custom Point of Sale application on top of Erply API. This API call is used by ERPLY’s own Touch POS, so the most up-to-date implementation is guaranteed.
Price list and promotion rules are very complicated and implementing them locally would also mean you need to download huge amounts of data. That is why we recommend to call calculateShoppingCart instead.
|Parameter name||Description||Possible value||Required|
|documentID||Sales document ID.||Integer|
|type||Possible values: INVWAYBILL, CASHINVOICE, WAYBILL, PREPAYMENT, OFFER, EXPORTINVOICE, RESERVATION, ORDER, INVOICE, CREDITINVOICE.|
Default value is CASHINVOICE.
|date||If omitted, current date will be used.||ISO date (yyyy-mm-dd)|
|warehouseID||Warehouse ID. |
You may specify either
If you do not specify neither location nor register, API automatically assumes you are selling from the first location in your locations list (by ID). All price lists and promotions associated with that location will apply, and that location's tax rate will be set to all items.
To be always sure of what location's price lists, promotions and taxes are being applied, we recommend to set this parameter explicitly.
An alternative to warehouseID.
|pricelistID||Price list ID. |
Set this value ONLY when you want to apply just this one price list to the sale and no others. In most cases, you do not need that! API will automatically apply any store, customer, or customer group price lists that have been defined, and will combine them automatically.
If not set, API will not make any assumptions about the customer, so no customer (or customer group) price lists will apply. If you want the sale to go to the "Default customer" or "POS Customer", send that customer's ID.
Exchange rate of the shopping cart currency against system's default currency. If the shopping cart is in system's default currency, this parameter does not have to be specified (but if you specify it, use
Pay attention to the way rates should be divided. If your shopping cart is in JPY and your account default currency is EUR, the expected value is
To get the current rate for a currency defined in Erply back office, see getCurrencies.
When using currencies, Erply can only apply price list prices, not any promotions.. Translating a promotion into a foreign currency has not been implemented yet. So, if you want to use the "currencyRate" input parameter, you must also specify
If currencyRate is not a valid positive decimal, API returns error 1014.
API calculateShoppingCart can also apply "a price from customer's previous quote". We assume that if a confirmed quote has been given to a customer (and it has not expired yet), then the items on the quote could be freely sold at the indicated price, as many times as the customer wants. If you want this feature, set this flag to 1.
If this flag has been set to 1, and there is a quote for the specified customer that has not expired yet, and it contains the specific product, the price from the quote will override price list price (even if quoted price is higher than price list price). Promotions, however, will still apply on top of the quote price as usual.
Currently, this flag only has an effect if you have not disabled the use of quote prices with configuration parameter
|Integer (1 or 0)|
|doNotApplyPromotions||If set to 1, then only price lists will be applied — not promotions.||Integer (1 or 0)|
|getAutomaticCoupons||If set to 1, API will also return a list of coupons that should be automatically printed from POS after the sale. See output field ||Integer|
Coupon codes (identifiers) that cashier has scanned.
Erply allows you to issue printed coupons to customers. Each printed coupon must have a unique identifier. In Erply backend, all issued coupons are listed in the Retail Chain » Issued Coupons module. A coupon is basically a method for invoking a sales promotion, so if customer returns to the store with a coupon and cashier scans it, a promotion will apply.
The recommended API workflow for accepting coupons is as follows:
NB! Coupons are not the same as "promotional codes", eg. "Get 20% off of all barbecue equipment with promo code JULY4" (which many be printed in an ad, or distributed in customer newsletter). As far as Erply is concerned, you do not need a coupon setup for that.
For that case, we recommend to define a manual promotion, set "JULY4" as its name, and have cashier to apply the promotion manually whenever customer presents the code.
Certain types of promotions allow to scan more than one coupon (the promotion will then apply multiple times):
|String (Comma-separated strings)|
Old deprecated name: "manualCampaignIDs"
IDs of promotions that cashier has applied manually.
In Erply, a promotion can be configured in three ways:
A promotion MAY be listed multiple times (if you want to apply it multiple times), but this only works with the following promotion types:
|String (Comma-separated integers)|
|doNotApplyInvoiceLevelPromotions||Integer (0 or 1)|
|taxExempt||Set a manual tax exemption to this sale.|
If the selected customer is already marked as being tax exempt on customer card, you do not need to send this flag.
If customer provides a tax exemption certificate number, you may attach it to the sale using the
|Integer (0 or 1)|
|euInvoiceType||Whether the sale is a domestic sale, a sale to another EU country or a sale to outside of the EU. Possible values are "DOMESTIC", "EU", "OUTSIDE_EU". The default tax rate suggested by API calculateShoppingCart depends on that.|
If this concept does not apply (your business is not in the EU), just leave the field unset.
|*************||Send invoice lines (ie., items and quantities) as a flat list. For each item, you may send the following input parameters. Replace # with a sequential number (0, 1, 2, 3 etc.)|
|productID#||ID of the product (SKU) sold.||Integer||yes|
In general, amount can be unlimited. However, to maintain performance, API applies each item-level promotion at most 1000 times. If you define a "Buy One, Get One" promotion and attempt to sell 5000 items, calculateShoppingCart will apply the discount to only 1000 items (instead of expected 2500, or every other item). We do not recommend to use item-level promotions in conjunction with large quantities.
|price#||Net price. |
Set this field ONLY if cashier has entered a price manually. In other cases, do NOT send this input field. API will itself find and set correct item price.
This parameter will overwrite product's price list price (or product card price, if no price list applies). On top of this price, API will apply promotion discounts and a manual discount.
|discount#||Manual discount. |
Set this field ONLY if cashier has set a manual discount for this invoice line. Manual discount will be applied cumulatively on top of promotion discounts; there is no way to "override" a promotional discount with a manual discount.
In general, price lists, discounts and promotions are applied by the API in the following order:
|vatrateID#||Set this field if you want a specific VAT / tax rate to be applied to this item. If not set, API will automatically determine the appropriate tax rate (which may be set at register, location, product group or product level). For a list of tax rates and IDs, see getVatRates.|
For reference, this is the priority (in decreasing order) of various tax rate settings that you can specify in ERPLY backend:
|rows||Array||Array elements have the following attributes:
|printAutomaticCoupons||Array||List of coupons that should be automatically printed to the customer after the sale has been completed. Array contents:
The recommended workflow is as follows:
Important! API assumes that you are calling
Eg.: let's say that customers are always given a coupon when they reach 200 points. If a customer currently has 180 points, you call
However, this assumption does not work if you are calling
Comma-separated list of coupons that had an effect on the given sale (from among all the coupons specified in input parameter
|appliedPromotions||Array||Promotions that were applied to the cart. Each array element contains the following fields:
|information||String||API analyzes the current shopping cart and customer history, and returns a plain-text message if it makes an interesting observation:
This field might not ber enabled by default, so let us know if you want to retrieve this information.
|freeExtraProductID||Integer||This field (and the next ones) notify the cashier if there is a promotion "Buy X and get product Y for free", promotion prerequisites have been fulfilled (customer has purchased X), but free gift Y has not been added to the basket yet. This field contains the product ID of the free gift item.|
|freeExtraProductCode||String||See previous. Product code of the free gift item.|
|freeExtraProductName||String||See previous. Name of the free gift item.|
|freeExtraNotification||String||See previous. Free-text notification about the free gift item that is available. Can be displayed in POS UI.|