Hello everyone!
Welcome back to another post in the Kaizen series!
This week, we will discuss handling product line items associated with the inventory modules—Quotes, Invoices, Purchase Orders, and Sales Orders.
What is a product line item?
On the Quote, Invoice, Purchase Order, Sales Order create or edit page, you add individual products in the Product Details section. This section also contains other details like the List Price, Quantity, Amount, Discount, and Tax. Every product and the corresponding details are called product line items.
In this post, we will discuss
- Adding product line items while inserting a quote (through the Insert Records API)
- Updating a quote by adding another product line item (through the Update Specific Records API)
The JSON input is similar while adding/updating an invoice, purchase order, and sales order.
1. Adding Product Line Items to a Quote
While adding a product to a quote you can,
a. Select a price book to associate with the product
b. Specify a different list price for the product
1. a. Selecting a price book to associate with the product
To associate a price book with the product, you must pass the ID of that price book in the input.
What happens when you pass the Price Book's ID?
- The discount on the product is automatically applied based on the range you specified in the price book.
- The cumulative tax (specified for the product) is automatically calculated based on the amount (after the discount).
- The List Price of the product specified in the associated price book is automatically taken for calculating the amount.
The sample input for Product_Details is as follows.
"Product_Details": [
{
"product": {
"id": "3652397000000491147"
},
"quantity": 100,
"product_description": "product_description",
"book": "3652397000000616007"
}
]
|
The following table gives information about each key in the Product_Details JSON Array.
Key
| Data Type
| Description
|
product
| JSON Object
| The ID of the product in the quote.
|
quantity
| Number
| The number of units of the product the quote is generated for. Accepts only positive integer values. The amount is calculated based on this number and the price for each unit.
|
book
| String
| The ID of the Price Book you have associated with the product.
|
product_description
| String
| Description of the product.
|
Here is a screenshot from the UI.
1.b. Specifying a different list price for the product
When the product does not have an associated price book or you want to give a different list price, you must specify the list price and the discount in the Product_Details array.
Otherwise, the system enters the value for the discount as 0 and takes the list price you specified while creating that product.
The sample input for the Product_Details JSON array is as follows.
"Product_Details": [
{
"product": {
"id": "3652397000000491147"
},
"quantity": 150,
"product_description": "product_description",
"Discount": 1000,
"list_price": 1100,
"line_tax": [
{
"percentage": 1,
"name": "VAT"
}
]
}
]
|
The following table gives information about each key in the Product_Details JSON Array.
Key
| Data Type
| Description
|
Product
| JSON Object
| ID of the product the quote generated for.
|
quantity
| Number
| The number of units of the product the quote is generated for. Accepts only positive integer values.
|
Discount
| Currency
| The discount, in decimals, you want to apply for the product. Accepts up to 16 digits before the decimal, and up to 9 digits after the decimal. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in the UI.
|
product_description
| String
| Description of the product.
|
list_price
| Currency
| The list price of the product.
|
line_tax
| JSON Array
| Contains the percentage and the name of the tax associated with the product.
|
percentage
| Percent
| The percentage of tax applied on the product. Accepts only numeric values, up to 5 digits.
|
name
| String
| The name of the tax applied on the product.
|
As mentioned earlier, the Product Details section encompasses the taxes applied for each product and the aggregate tax applied to the Sub Total of the quote or any other inventory module.
You can specify the different taxes you want to apply for your products in the CRM UI.
You can add them under Setup > Customization > Modules and Fields > Products as shown in the below image.
You can use these configured values as inputs in the API.
Adding taxes to the product while creating/updating an inventory module
When you add a product to an inventory module, to apply the taxes to that product, you must specify the tax details in the line_tax JSON array inside Product_Details.
You must specify the percentage and the name of the tax associated with the product as JSON objects.
You cannot specify the amount as the system calculates it automatically based on the quantity.
Example:
"Product_Details": [
{
"product": {
"id": "3652397000001363004"
},
"quantity": 100,
"Discount": 20.1,
"product_description": "product_description",
"line_tax": [
{
"percentage": 10,
"name": "Sales Tax"
},
{
"percentage": 1,
"name": "Vat"
}
]
}
]
|
Adding aggregate tax to the quote or other inventory modules
This is the tax that you want to apply to the Sub Total of the line items while generating the invoice, quote, sales order, or purchase order. The taxes you specify in the $line_tax key are added to the ones already applied to the product through the line_tax key.
The $line_tax key is present outside the Product_Details JSON array.
The structure for this JSON array is as follows.
"Product_Details": [
{
"product": {
"id": "3652397000001363004"
},
"quantity": 100,
"product_description": "product_description",
"line_tax": [
{
"percentage": 10,
"name": "Sales Tax"
},
{
"percentage": 1,
"name": "Vat"
}
]
}
],
"$line_tax": [
{
"percentage": 1.5,
"name": "Common Tax",
"id": "3652397000001376005"
}
]
|
Key
| Data type
| Description
|
| | Contains the name, ID, and the percentage of the tax you want to apply to the quote.
|
percentage
| Percent
| The percentage of tax applied on the quote. Accepts only numeric values, up to 5 digits.
|
name
| String
| The name of the tax.
|
id
| String
| The unique ID of the tax.
|
Note
Make a GET request to "{{api-domain}}/crm/v2/org/taxes" to obtain the IDs of all the taxes for your organization.
The below image shows the data corresponding to the line_tax and $line_tax keys in the UI for a quote.
Points to note
- For Product_Details
When you have associated a price book with an inventory module, and you include the key and value for Discount inside Product_Details, this discount value overrides the discount calculated from the price book. - For line_tax
You must specify the percentage of tax in every JSON object inside the line_tax array.
2. Updating a Quote by adding Product Line Items
You can associate multiple products to a quote.
While updating a quote, you can add/update/remove a line item.
Let us consider an example where you have five line items in a quote, and you want to remove two line items, and add a new one.
In this case, you must
- Pass the IDs of the line items you want to retain as individual JSON objects.
- Add the new line item with the required details as a new JSON object.
- Do not include any details about the line item you want to remove. When you do not specify the ID of any line item, the system deletes it automatically.
A sample JSON structure for the above scenario is as follows.
"Product_Details": [
{
"id": "3652397000001377174"
},
{
"id": "3652397000001378168"
},
{
"id": "3652397000001379172"
},
{
"product": {
"id": "3652397000001351002"
},
"quantity": 100,
"book": "3652397000000616007"
}
]
|
To obtain the ID of the existing line item, make a GET request to fetch the Quote you want to update. The response contains the ID of the existing line item in the Product_Details array.
Note
- You can add a maximum of 200 line items to an inventory module.
We hope you found this post useful. Please reach out to us if you have any questions, or let us know in the comment section.
Cheers!