Pricing Sublist / Pricing Matrix
The Pricing sublist is often referred to as a pricing matrix, since there can be multiple prices specified for an item as determined by one or more price levels and one or more quantity levels.
Functionally, the Pricing sublist shares many of the characteristics of list sublists. However, scripting to the Pricing sublist is not like scripting to other sublists in NetSuite. For this reason, you should read the following topics to learn about using SuiteScript on the Pricing sublist.
The screenshots in this section depict the NetSuite UI prior to Version 2010 Release 2.
For general information about item pricing, see these topics in the NetSuite Help Center:
To see which records the Pricing sublist appears on, see Records that Include the Pricing Sublist.
The Pricing Matrix
Depending on the features enabled in your account, the Pricing sublist on many item records can resemble a matrix of rows and columns of various prices (see figure). To access the price values on a per-row, per-column basis, you must use matrix APIs. These APIs are a subset of the standard APIs that are more commonly used when scripting with other sublists. See Matrix Sublist APIs and Standard Sublist APIs for more information.
Non-matrix sublist APIs can also be used on the Pricing sublist. However, they are not used to get or set values considered to be part of the pricing matrix. For information about when to use matrix and non-matrix APIs on the Pricing sublist, see Matrix Sublist APIs and Standard Sublist APIs.
The figure below provides an overview of the rows and columns considered to be the pricing matrix. As previously stated, the configuration of the Pricing sublist greatly depends on the features enabled in your account. However, regardless of the features set, all configurations will have some variation of a row / column matrix layout like the one shown below.
This code snippet shows the kind of values you will typically set when working with price values in the pricing matrix. The internal ID of the Pricing sublist, as well as its field IDs, will change depending on the features enabled in your account.
See Pricing Sublist Feature Dependencies and Pricing Sublist Internal IDs for more information.
Example
record.getMatrixSublistValue ({
sublistId: 'price',
fieldId: 'price',
column: 1,
line: 2
});
In this sample you:
-
Specify the sublist internal ID (
price). -
Specify the internal ID of the pricing field (which will generally be
price).Important:Although the UI labels in this figure show field names such as Alternate Price 1, Alternate Price 2, and Online Price, the internal ID for the fieldId parameter is still
price. The only exception to this is described in Pricing Sublist Field IDs for the currency field. -
Specify the line number (row) of the price you want to get (in this sample, you are getting the value in row 2 - this is the price for Alternate Price 1 ).
-
Specify the column number you want to get the value for (in this sample, you are getting the value in column 1 for Alternate Price 1 ).
|
1 |
Column one |
|
2 |
Row two |
Price is typically the internal ID for the fieldId parameter.
Pricing Sublist Feature Dependencies
There are three features that, if enabled or disabled in your account, can affect the overall functionality of the Pricing sublist, its appearance in the UI, and the internal IDs that are referenced in SuiteScript.
You can check which of these features are enabled by looking in the UI, or by calling the runtime.isFeatureInEffect(options) method and specifying the feature internal ID.
The features that affect the Pricing sublist are:
If none of these features are enabled in your account, then there is no Pricing sublist on the item record, and the field that holds the item price appears on the Basic subtab as Sales Price. The internal ID for this field is rate. You do not use sublist methods to set or get values on rate. Instead, use field methods.
Multiple Currencies
This feature allows for item prices to be set in multiple currencies. Separate pricing is specified for each currency. On the Pricing sublist you will see subtabs with the name of the currencies specified in your account (see figure).
See Pricing Sublist ID to learn how to determine the internal ID of the Pricing sublist based on whether the Multiple Currencies feature is enabled.
In the UI, you can check if this feature is enabled by looking at the Pricing sublist itself or by going to Setup > Company > Enable Features. On the Company tab, the Multiple Currencies box will be selected if this feature is enabled. Note: Only a NetSuite administrator can enable this feature.
In SuiteScript, you can get the feature status by writing something similar to:
var multiCurrency = runtime.isFeatureInEffect ({
feature: 'MULTICURRENCY'
});
See Pricing Sublist Code Sample for more details.
Multiple Prices
This feature allows different prices to be specified for different conditions or types of customers. This requires that Price Levels are set up. There are a set of standard Price Levels provided by NetSuite, and these can be changed or extended by the customer.
This figure shows the Pricing sublist with the Multiple Prices feature enabled. Notice you can specify multiple prices for the same item.
By comparison, this figure shows the Pricing sublist with the Multiple Prices feature disabled. You can set only one price for the item.
In the UI, you can check if this feature is enabled by looking at the Pricing sublist itself or by going to Setup > Company > Enable Features. On the Transactions subtab, the Multiple Prices box will be selected if this feature is enabled. Note: Only a NetSuite administrator can enable this feature.
In SuiteScript, you can get the feature status by writing something similar to:
var multiPrice = runtime.isFeatureInEffect ({
feature: 'MULTIPRICE'
});
See Pricing Sublist Code Sample for more details.
Quantity Pricing
This feature allows the item price to vary based on the quantity of items sold. Specifically, this feature allows different quantity levels to be specified and allows the price to vary at each quantity level.
This figure shows the Pricing sublist with the Quantity Pricing feature enabled.
When the Quantity Pricing feature is enabled, an administrator can specify the number of Qty columns that appear on the Pricing sublist. The following figure shows that four Qty columns have been specified. Set the Qty preference by going to Setup > Accounting > Accounting Preferences > Items & Transactions. In the Maximum # of Quantity-based Price Levels field, specify the number of columns.
Item pricing is determined by values specified in the Qty fields.
By comparison, this figure shows the Pricing sublist with the Quantity Pricing feature disabled. Item prices are not determined by the quantities specified.
No Qty fields exist in the following image:
In the UI, you can check if this feature is enabled by looking at the Pricing sublist itself or by going to Setup > Company > Enable Features. On the Transactions subtab, the Quantity Pricing box will be selected if this feature is enabled. Note: Only a NetSuite administrator can enable this feature.
In SuiteScript, you can get the feature status by writing something similar to:
var quantityPricing = runtime.isFeatureInEffect ({
feature: 'QUANTITYPRICING'
});
See Pricing Sublist Code Sample for more details.
Pricing Sublist Internal IDs
As discussed in Pricing Sublist Feature Dependencies, the Pricing sublist looks and functions different depending on the features set in your account.
See Pricing Sublist ID for the internal ID of the Pricing sublist depending on features enabled in your account.
See Pricing Sublist Field IDs for all other field IDs associated with this sublist.
Pricing Sublist ID
In SuiteScript, the internal ID of the Pricing sublist is determined by the features enabled in your NetSuite account.
If the Multiple Currencies feature is not enabled in your account, the internal ID for the Pricing sublist is price. This means that you will set the sublist parameter in APIs such as Record.getMatrixHeaderField(options) and Record.setMatrixHeaderValue(options) to price.
If Multiple Currencies is enabled, then there are separate Pricing sublists per currency (see figure).
Each currency pricing list will have its own internal ID. For example, the internal ID for the currency called USA will be price1. This ID reflects the internal ID of the sublist (price) and the internal ID of the USA currency (1).
The internal ID for the Canadian dollar sublist will be price3. This reflects the internal ID of the sublist (price) and the internal ID of the Canadian dollar currency (3).
This figure shows the currencies that have been set in this account. Notice the Internal ID for each currency is the numeric value appended to price. When the Multiple Currencies feature is enabled, you can see the internal ID for each currency by going to Lists > Accounting > Currencies.
Based on the internal ID shown in the figure above, you will set the sublistId parameter in APIs such as Record.getMatrixHeaderField(options) as follows (fieldId and column parameter values are examples values):
// if scripting on the USA dollar tab:
record.getMatrixHeaderField ({
sublistId: price1,
fieldId: fldname,
column: column
})
// if scription on the British pound tab:
record.getMatrixHeaderField ({
sublistId: price2,
fieldId: fldname,
column: column
})
// if scripting on the Canadian dollar tab:
record.getMatrixHeaderField ({
sublistId: price3,
fieldId: fldname,
column: column
})
// if scripting on the Euro tab:
record.getMatrixHeaderField({
sublistId: price4,
fieldId: fldname,
column: column
})
For topics related to this one, see Pricing Sublist Feature Dependencies.
Pricing Sublist Field IDs
This table provides the internal IDs for all fields associated with the Pricing sublist. Field types are categorized as matrix fields, sublist fields, and body fields.
|
Field UI Label |
Field Internal ID |
Field Type |
Required |
Field Notes |
|---|---|---|---|---|
|
Matrix Fields |
||||
|
Base Price Qty |
|
string |
true |
The price for that level and that quantity. See Figure 1 - Matrix Fields.
Important:
When using matrix APIs (that is, any API that has the word Matrix in its name), price will generally be the value specified for the fieldId parameter. The exception to this is if the Multiple Currencies feature is enabled in your account. |
|
Sublist Fields |
||||
|
Default Discount % |
|
— |
— |
See Figure 2 - Sublist Fields. See also Standard Sublist APIs for a code sample that references this internal ID. |
|
— |
|
— |
— |
The currency field is a hidden field. It is not visible in the UI. See Figure 2 - Sublist Fields. This field is scriptable only when the Multiple Currencies feature is enabled. The internal IDs for the fieldId parameter in matrix APIs will be price1currency, price2currency, pricecurrency3, etc., to reflect the currency internal ID. |
|
Price Level |
|
— |
— |
The pricelevel for this price. See Figure 2 - Sublist Fields. See also Standard Sublist APIs for a code sample that references this internal ID. |
|
Body Fields |
||||
|
Quantity Pricing Schedule |
|
select |
false |
If a quantity pricing schedule has been specified in the UI drop-down, item prices will be calculated for the pricing matrix according to the specified schedule. See Figure 3 - Body Fields. Also note that the value of the quantity pricing schedule sets the value of the Calculate Quantity Discounts (overallquantitypricingtype) field. Use field methods in the N/record Module or N/currentRecord Module module to access this field. |
|
Calculate Quantity Discounts |
|
select |
false |
Used to determine the quantity amount at the time the item is priced on the order. (This field does not change price settings in the matrix). See Figure 3 - Body Fields. Use field methods in the N/record Module or N/currentRecord Module module to access this field. |
|
Use Marginal Rates |
|
checkbox |
false |
Used to determine how the quantity discounts are applied at the time the item is priced on the order with a specified quantity. (This field does not change the price settings in the matrix.) See Figure 3 - Body Fields. Use field methods in the N/record Module or N/currentRecord Module module to access this field. |
|
Pricing Group |
|
select |
false |
Used to provide customer- specific pricing. Could affect the pricing at the time the item is placed on the order and associated with a specific customer. See Figure 3 - Body Fields. Use field methods in the N/record Module or N/currentRecord Module module to access this field. |
Figure 1 - Matrix Fields
Pricing sublist matrix field.
Figure 2 - Sublist Fields
Use non-matrix sublist APIs to get or set values for these pricing sublist fields.
Figure 3 - Body Fields
Use standard field APIs to get or set values for Pricing sublist body fields.
Pricing Sublist Code Sample
This sample shows how to determine which pricing-related features are enabled in your account. It then shows how to programmatically determine the internal ID for the Pricing sublist itself, and then verify whether a Quantity Schedule has been applied to the items in this list. The script also shows how to set item prices and quantity levels depending on various conditions set within the pricing matrix.
If your browser is inserting scroll bars in this code sample, maximize your browser window, or expand the main frame that this sample appears in.
// Check the features enabled in the account. See Pricing Sublist Feature Dependencies for
// details on why this is important.
var multiCurrency = runtime.isFeatureInEffect({
feature: 'MULTICURRENCY'
});
var multiPrice = runtime.isFeatureInEffect({
feature: 'MULTIPRICE'
});
var quantityPricing = runtime.isFeatureInEffect({
feature: 'QUANTITYPRICING'
});
// Set the name of the Price sublist based on which features are enabled and currency type.
// See Pricing Sublist Internal IDs for details on why this is important.
var priceID;
var currencyID = 'EUR';
// Set the ID for the sublist and the price field. Note that if all pricing-related features
// are disabled, you will set the price in the rate field. See Pricing Sublist Feature Dependencies
// for details.
if (multiCurrency === true && multiPrice === false && quantityPricing === false)
priceID = 'rate';
else {
priceID = 'price';
if (multiCurrency === true){
var internalId = search.create ({
type: search.Type.CURRENCY,
filters: [{
name: 'symbol',
operator: search.Operator.CONTAINS,
values: currencyID
}],
});
priceId = priceID + internalId;
}
}
// Verify that the item is using a Quantity Schedule
// If a Quantity Schedule is used, only the base price needs to be set.
// All other prices will be set according to the schedule.
var itemRecord = record.load ({
type: record.Type.INVENTORY_ITEM,
id: itemId
});
var qtyPriceSchedule = itemRecord.getValue({
fieldId: 'quantitypricingschedule'
});
// Set the base price
var basePrice = 100;
// You must select, set, and then commit the sublist line you want to change.
itemRecord.selectLine({
sublistId: priceID,
line: 1
});
itemRecord.setCurrentMatrixSublistValue({
sublistId: priceID,
fieldId: 'price',
column: 1,
value: basePrice
});
itemRecord.commitLine({
sublistId: priceID
});
// Get the number of columns in the price matrix
// Each column represents a different quantity level
columnCount = itemRecord.getMatrixHeaderCount({
sublistId: priceID,
fieldId: 'price'
});
// Set the base price in each quantity of the price matrix for a specific sublist, for example, currency
// Set the base price in each quantity
for (var j = 1; j <= columnCount; j++){
// Set the price for this cell of the matrix
itemRecord.selectLine({
sublistId: priceID,
line: 1
});
itemRecord.setCurrentMatrixSublistValue({
sublistId: priceID,
fieldId: 'price',
column: j,
value: currencyBasePrice
});
itemRecord.commitLine({
sublistId: priceID
});
}
// Display the full price matrix for a specific currency as an HTML table
// get the size of the matrix
var quantityLevels = itemRecord.getMatrixHeaderCount({
sublistId: priceID,
fieldId: 'price'
});
var priceLevels = itemRecord.getLineCount({
sublistId: priceID
});
var priceName = "";
var priceNameField = 'pricelevel';
var itemPrice = 0;
var fieldObj = null;
// create an xml table to present the results
var strName = '<table>';
if (quantityLevels > 1){
strName += '<tr>';
// write out the quantity levels as the first row
for (var j = 1; j <= quantityLevels; j++){
strName += '<td>';
fieldObj = itemRecord.getMatrixHeaderField( {
sublistId: priceID,
fieldId: 'price',
column: j
});
if (fieldObj != null){
strName += fieldObj.getLabel();
}
strName += j;
strName += '</td>';
strName += '<td>';
// this matrix API obtains the value of the Quantity level
strName += itemRecord.getMatrixHeaderValue({
sublistId: priceID,
fieldId: 'price',
column: j
});
strName += '</td>';
}
strName += '</tr>';
}
// loop through the matrix one row at a time
for (var i = 1; i <= priceLevels; i++){
strName += '<tr>';
// loop through each column of the matrix
for (j = 1; j <= quantityLevels; j++){
// get the price for this cell of the matrix
itemPrice = itemRecord.getLineItemMatrixValue( priceID, 'price', i, j);
// Get the name of the price level. Note: you will use a standard
// sublist API and not a matrix API for this.
priceName = itemRecord.getSublistText({
sublistId: priceID,
fieldId: priceNameField,
line: i
});
strName += '<td>';
strName += priceName;
strName += '</td>';
strName += '<td>';
strName += itemPrice;
strName += '</td>';
}
strName += '</tr>';
}
strName += '</table>';
Matrix Sublist APIs and Standard Sublist APIs
To get or set values in the pricing matrix, you will use matrix APIs (within N/record Module and N/currentRecord Module modules).
If you want to get or set non-matrix fields, you will use all non-matrix sublist or field (within the N/record Module or N/currentRecord Module modules), depending on which fields you are trying to access.
See The Pricing Matrix for information about the pricing matrix. See Pricing Sublist Field IDs for information about the differences among matrix, non-matrix, and body sublist fields.
Matrix APIs
The following are considered to be matrix APIs for use on the Pricing sublist. Use these APIs to get or set matrix fields. See Pricing Sublist Field IDs to learn which fields are considered matrix fields.
Click the following links to see the API documentation for each matrix API. Also see the figures below for a visual representation for where on the pricing matrix each matrix API executes.
On matrix header fields, use Record.getMatrixHeaderField(options), Record.getMatrixHeaderValue(options), and Record.getMatrixHeaderCount(options).
When on an existing line in the matrix, use Record.getCurrentMatrixSublistValue(options) and Record.setCurrentMatrixSublistValue(options) to get and set the price on that line in the specific column, respectively.
For all other lines in the matrix, use Record.getMatrixSublistValue(options) and Record.findMatrixSublistLineWithValue(options).
Standard Sublist APIs
If you want to reference the other fields in the Pricing sublist, such as currency, name, or discount, use the existing Record.getSublistValue(options) and pass in the existing fieldId (for example: price1currency). Also see Pricing Sublist Field IDs, which specifies which fields on the Pricing sublist can be set using standard sublist APIs (within the N/record Module and N/currentRecord Module modules).
Example:
// load an item record
var record = record.load ({
type: record.Type.INVENTORY_ITEM,
id: 536 // for example - use your own record id
});
// get the value of the currency field on line 2
var currency = record.getSublistValue({
sublistId: 'price1',
fieldId: 'currency',
line: '2'
});
// get the value of the pricelevelname field on line 2
var pricelevelname2 = record.getSublistValue({
sublistId: 'price1',
fieldId: 'pricelevel',
line: '2'
});
var pricelevelname3 = record.getSublistValue({
sublistId: 'price1',
fieldId: 'pricelevel',
line: '3'
});
var pricelevelname4 = record.getSublistValue({
sublistId: 'price1',
fieldId: 'pricelevel',
line: '4'
});
// returns the discount from line item 2
var discount2 = record.getSublistValue({
sublistId: 'price1',
fieldId: 'discount',
line: '2'
});
var discount3 = record.getSublistValue({
sublistId: 'price1',
fieldId: 'discount',
line: '3'
});
var discount4 = record.getSublistValue({
sublistId: 'price1',
fieldId: 'discount',
line: '4'
});
Records that Include the Pricing Sublist
The Pricing sublist appears on the following records that are scriptable using SuiteScript: Assembly Item, Lot Numbered Assembly Item, Serialized Assembly Item, Lot Numbered Inventory Item, Serialized Inventory Item, Gift Certificate Item, Kit Item, Inventory Item.