Requests that create and apply price levels

A price level is a List object that is used on a customer/customer job, or on an individual line item in an invoice, sales receipt, sales order, or credit memo. (This is accomplished by using the PriceLevelRef aggregate in the Add and Mod requests for each of these supported objects.)

When applied to customers or customer jobs, the price level allows you to set custom pricing on a per customer or a per job basis. That is, after you use a price level with a customer or customer job, QuickBooks automatically uses that custom price as the default price each time you create an invoice, sales receipt, sales order, or credit memo for that customer or customer job.

Of course, price levels can also be dynamically applied to the individual line items in an invoice, sales receipt, sales order, or credit memo: you don’t have to simply accept the default customer price level.

Notice that if you use price levels on a per line item basis, and have created price levels, the QuickBooks UI automatically provides support where needed, for example, for each line item in the Sales Order form, the Rate column is a drop-down list that lets the user select any of the available price levels.

There are two types of price levels: Fixed Percent and Per Item. The type is specified at price level creation time: the type cannot be changed later by a PriceLevelMod operation. Of these two types, the Fixed Percent type is supported by the QuickBooks Pro tier and above, while the Per Item type is supported only by the QuickBooks Premier and Enterprise tiers.

• The Fixed Percent price level modifies any item’s base price by a fixed percentage.
• The Per Item price level supports custom prices on individual items.

You need to use price levels any time special prices are needed; for midnight madness sales, preferred customers, sales-rep discretionary pricing, and so on.

In order for price levels to have any effect, or become available for use in transactions, they must be enabled in the Sales & Customers preferences for the company file. So, you need to check for this by using a PreferencesQuery and examine the SalesAndCustomersPreferences aggregate within the response. In particular, the sub- aggregate PriceLevels field IsUsingPriceLevels must contain the value True; otherwise price levels are not available.

Based on this check, your own application can respond appropriately, either by displaying information to the user and/or disabling your own application’s price-level oriented features. Notice that your application cannot enable price levels via the SDK.

The PriceLevel is a List object, so it is manipulated in the same general way as other List objects. You create one using PriceLevelAdd, modify it using PriceLevelMod (notice that you cannot modify the type, fixed versus per item), query for price levels using PriceLevelQuery, and delete a PriceLevel using ListDel. Also, PriceLevel is supported in the related queries, for example, ListDeletedQuery can provide a list of recently deleted PriceLevels, CustomerQuery can return the price level (if any) linked to the customer, and so on.

Notice that the PriceLevelQuery contains an ItemRef, which allows you to find all price levels that apply to that item.This is very useful when selecting the price level for an individual line item because you’ll get a runtime error 3140 if you specify an inapplicable price level for a given item.

Notice that you use positive values to increase the price from the base price and negative ones to decrease from the base price.

Similar to adding a group item or invoice line, when you create a per item price level, you supply a list of PriceLevelPerItem aggregates that reference an Item and supply a custom price/percent or a percentage adjustment relative to either the standard price, the item cost, or the currently existing custom price. (This is useful on PriceLevelMod requests.)

Once a user links a customer to a price level, all sales transactions for that customer will by default use the item prices set by the price level. This differs from versions of QuickBooks prior to 2005, where an invoice entered from the SDK defaulted to the standard price for each line item (unless a price was specified).

In the following subsections, creating a fixed percent price level is described first, then creating a per item price level is described.

You can create a Fixed Percent type price level using the following qbXML:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<?qbxml version="4.0"?>
<QBXML>
    <QBXMLMsgsRq onError = "stopOnError">
        <PriceLevelAddRq requestID = "0">
            <PriceLevelAdd>
                <Name>Special Customer Discount</Name>
                <IsActive>true</IsActive>
                <PriceLevelFixedPercentage>-5</PriceLevelFixedPercentage>
            </PriceLevelAdd>
        </PriceLevelAddRq>
    </QBXMLMsgsRq>
</QBXML>

In the above sample qbXML, a price level with the name “Special Customer Discount” is created with a fixed percentage amount of -5%. This means there will be a 5% reduction of the Rate (price each) of the sales price of the item line item where this price level is applied in an invoice, sales order, and so on. The IsActive tag by default is true, so you don’t need to supply it. It is shown for completeness. In a PriceLevelAdd you might set it to false if you were preparing for a sale and didn’t want this price level to show up yet. (In a PriceLeveMod, you would set it to false if you wanted to discontinue a particular discount.)

The following figures show how a user would apply price level to a line in a sales order or invoice in the QuickBooks UI. The first figure shows the standard item price (in the Rate column) for the line item, and the total amount. The second figure shows the dropdown list that appears in the Rate column if Price Levels are enabled and if there are any existing price levels, and if a price level has not been applied to the customer. Notice the Special Customer Discount price level that is being created.

In the third figure, notice that the Rate and Amount have changed after the user selected Special Customer Discount from the dropdown list of price levels. The Rate column reflects the 5% discount for each item, and the total (Amount column) also reflects it.

An item in the UI before a price level is applied:

Applying the level in the QuickBooks UI:

Line item rate and amount after applying the price level in QuickBooks:

What would happen if the price level were applied to the customer? Then the default price shown in the Rate column (and the total in the Amount column) would automatically adjust to the price level. The user could still select from the dropdown list of price levels, however.

Creating a per item price for an item results in the creation of a custom price for the item that is visible in the QuickBooks Edit Price Level form. Consequently, you can apply discounts to this custom price as well as to the item’s cost and standard sales price.

In the per item price level, you can choose between two approaches. You can create a price level that specifies ONE of the following prices:

• A fixed price for an item or a fixed percentage discount to be applied to an item’s cost
• A discount percentage applied to an item’s cost, standard sales price, or current custom price

The following sample qbXML shows how to build a per item price level using a discount percentage applied to an item’s cost.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

<?qbxml version="4.0"?>
<QBXML>
    <QBXMLMsgsRq onError = "stopOnError">
        <PriceLevelAddRq requestID = "0">
            <PriceLevelAdd>
                <Name>Cost-Plus Sale</Name>
                <IsActive>true</IsActive>
                <PriceLevelPerItem>
                    <ItemRef>
                        <FullName>Bolts</FullName>
                        <AdjustPercentage>10</AdjustPercentage>
                        <AdjustRelativeTo>Cost</AdjustRelativeTo>
                    </PriceLevelPerItem>
                </PriceLevelAdd>
            </PriceLevelAddRq>
        </QBXMLMsgsRq>
    </QBXML>

In this sample, the Cost-Plus Sale price level specifies a price for the Bolts item that is 10 percent more than the cost.

You can apply a price level to a customer when you create the customer (CustomerAddRq) or when you modify the customer (CustomerModRq). You’ll notice that the customer can have only one price level applied at a time, however. The following sample qbXML shows the price level “Cost-Plus Sale” applied to the customer Geraldine Wilson when that customer is being added to QuickBooks.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

<?qbxml version="4.0"?>
<QBXML>
    <QBXMLMsgsRq onError = "stopOnError">
        <CustomerAddRq requestID = "2">
            <CustomerAdd>
                <Name>Geraldine Wilson</Name>
                <FirstName>Geraldine</FirstName>
                <LastName>Wilson</LastName>
                <BillAddress>
                    <Addr1>123 Main St.</Addr1>
                    <City>Mountain View</City>
                    <State>CA</State>
                    <PostalCode>94566</PostalCode>
                </BillAddress>
                <Phone>650-944-1111</Phone>
                <PriceLevelRef>
                    <FullName>Cost-Plus Sale</FullName>
                </PriceLevelRef>
            </CustomerAdd>
        </CustomerAddRq>
    </QBXMLMsgsRq>
</QBXML>

If you want to use the SDK to apply price levels to individual line items in the various types of transactions, for example, invoice, sales orders, sales receipts, and so on, you can do so by including a PriceLevelRef in the line item Add or Mod aggregate. For example, in an InvoiceAdd request, you can specify a price level for an invoice line item inside the InvoiceLineAdd aggregate as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<InvoiceLineAdd>
    <ItemRef>
        <FullName>Bolts</FullName>
    </ItemRef>
    <Desc>Bag O’ Bolts</Desc>
    <Quantity>10</Quantity>
    <PriceLevelRef>
        <FullName>Special Customer Discount</FullName>
    </PriceLevelRef>
</InvoiceLineAdd>

It is important to note that for per item price levels, the item inside the ItemRef above must support the price level inside the PriceLevelRef. (For Fixed Percent price levels, this is not an issue.)

Notice that the Amount tag has been omitted. This is calculated by QuickBooks automatically from the Rate, or, in this case the Rate as automatically adjusted by the price level.