Why

Retrieving data is usually the most time consuming part of a calculation. The method api.currentItem() is the best performing way and should be the first option to get data for the current item being processed in your item list (i.e. PLI, PGI or CFS). It only accesses data already loaded in memory of the calculation engine without the need of an additional database query. The alternatives are api.product(), api.find() or api.currentContext(sku), all being slower for this.

Caution: api.currentItem() has a special behavior in 1st execution of a line item - see the API doc for detail.

When to Use

In the line item logic calculations (PLI, PGI, CFS) if you need to access the data of the current item being processed. You can then retrieve an attribute using:

return api.currentItem("attributeName")

This is a recommended practice because the current item is already loaded in the memory of the calculation engine and api.find() would perform an additional database query for each line item which would cause poor performance for larger PLI or PGI sets.

When Not Possible to Use

1. If you need to access data that is not available on the item. In that case you utilize api.product() or api.find().

2. If you need to access a different line item from the list, you can utilize api.currentContext(sku) or api.find().