all data is live and searchable
« Back . [api documentation and samples] . [view sample]
Main Web API Documentation Information
Actual Page/Function Name:
addInvoiceLineItem
Human Readable Name or Caption:
Add Invoice Line Item
Page/Function Description:
This method will add an invoice line item to the database. It is very important that you get all of the data correct. This is how all of the quantities, sales revenue, tax liabilities, and eventual cost of goods sold are tracked through the system.
Page/Function Output Type:
API - JSON or WDDX
Categories:
eComm,invoice
Extra Page/Function Notes:


Parameters
Scope Name Type Default Description Required Alternates Known Values
Arguments CITY_TAX Numeric 0 Pass in the city tax for the line item. As a note, there are numerous tax fields. Please check to see what way your corp wants to account for them. There are city, state, county, and five custom fields for taxes. No
Arguments CORP_ID Numeric 0 Pass in the corp id number. This is your corporation ID or your business world number. This is required and will be validated. The default is 0, but will be checked for a real number. Yes
Arguments COUNTY_TAX Numeric 0 Pass in the county tax. No
Arguments CUSTOMER_ID Numeric 1 Pass in the customer id number. Pass in the value of 1 if it's a counter sale (invoice type=3) or if the customer is unknown. Pass in the customer's id number if it's a customer invoice. A valid customer id is required for these invoice types: 2=Customer Invoice, 4=Rental Ticket, 7=Quote, 8=Transition Invoice. Yes
Arguments DISCOUNT_CAMPAIGN String Pass in the discount campaign name, if any. A discount campaign is used in coordination with the discount rate. This is used to record notes on why a discount was done- a specific marketing campaign, a sale, or a category of discounts. Examples: 4th of July sale, Black Friday, Big Summer Blowout, Veteran, VIP, Friends and Family discount, etc. No
Arguments IN_LINE_DISCOUNT_EXTENDED Numeric 0 Pass in the extended dollar amount of the discount. This is the total dollars to take off. No
Arguments IN_LINE_DISCOUNT_PER_LINE Numeric 0 Pass in the dollar amount of the discount per single item. This does not take the quantity into effect. No
Arguments IN_LINE_DISCOUNT_PERCENTAGE Numeric 0 Pass in the discount percentage as a number. This needs to be somewhere between 0 and 100. Ex: 12.00, 27, 45.99. No
Arguments INVENTORY_TYPE_ID Numeric 5 Pass in the inventory type id. The two main values that get passed in are 5 (normal items) or 7 (unlimited items). Some others are 2=Trailer, 3=Vehicle, 4=Topper, 5=Parts, 6=Flatbeds, 7=Labor/Service, 8=Specific Unit, 9=Rental, and 10=Balance Sheet Items. Yes
Arguments INVOICE_NUMBER Numeric 0 Pass in the invoice number. This is the primary key that ties the main invoice to the line items. As a note, you should have already ran the startMainInvoice method. Use that id number to pass to this method. Yes
Arguments INVOICE_TYPE_ID Numeric 2 Pass in the invoice type id number. 2=Customer Invoice, 3=Counter Sale, 4=Rental Ticket, 5=Internal-Repair, 6=Transfer, 7=Quote, 8=Transition Invoice. As a side note, a valid customer id is needed for invoice types 2, 4, 7, and 8. Yes
Arguments ITEM_COST Numeric 0 Pass in the item cost. This is what the company paid for the item. As a side note, this value gets included in the P&L (profit and loss), cost of goods sold, and other financials within the system. It is very important for it to be correct. Also as a note, this is per item- it will be cascaded later on when it gets multiplied by a quantity. Yes
Arguments ITEM_PRICE Numeric 0 Pass in the item price. This is the main sales price for a single item. This value will be multiplied by the quantity and then goes to the P&L in the revenue portion. If a discount is used, it actually needs to be reflected in this item price. There is another field called original list price where you can put the original value. Yes
Arguments LINE_DESCRIPTION String Pass in the line item description. There is a maximum of 255 characters. Yes
Arguments LINE_ITEM_DATE String Pass in the line item date. This should be the same date as the main invoice date. This is how the system looks up inventory usage based on dates. Yes
Arguments LINE_ITEM_SORT Numeric 100 Pass in the line item sort number. This is optional and allows you to manually manipulate the sort order of the line items. The system is set up to first check the sort order and then check the auto id number for the line item. No
Arguments LINE_QUANTITY Numeric 0 Pass in the quantity. This will be multiplied by the price and entered into the database. Pass in a positive value for a sale and a negative value for a return. However many you sold is usually a positive number. Yes
Arguments LINE_RFID_TAG_NUMBER String Pass in the line specific control/RFID tag number. As a side note, if you are using sub inventory... you will want to get the RFID tag number from the sub being used and push it through here on the add parent invoice line item. That helps to complete the tie-ins. No
Arguments LINE_SHOW Numeric 1 Pass in a 1 for show and 0 for hide. If a value is hidden (0), it can't have a price or extended price. It can still have a quantity and a cost. Otherwise it messes up the math. No
Arguments ORIGINAL_LIST_PRICE Numeric 0 Pass in the original list price before a discount is applied. This will be the same as the normal price unless discounts are being applied. This is for a single item. Yes
Arguments ORIGINAL_LIST_PRICE_EXTENDED Numeric 0 Pass in the original list price times the quantity before a discount is applied. Yes
Arguments OTHER_TAX_1 Numeric 0 Pass in the other tax 1 amount. These are custom and set per location. No
Arguments OTHER_TAX_2 Numeric 0 Pass in the other tax 2 amount. These are custom and set per location. No
Arguments OTHER_TAX_3 Numeric 0 Pass in the other tax 3 amount. These are custom and set per location. No
Arguments OTHER_TAX_4 Numeric 0 Pass in the other tax 4 amount. These are custom and set per location. No
Arguments OTHER_TAX_5 Numeric 0 Pass in the other tax 5 amount. These are custom and set per location. No
Arguments OUT_OF_AREA_TAX Numeric 0 Pass in the out of area tax. This particular tax is a special one for bigger items like stock units. Some counties have special rules for where you buy it vs. where you register it. No
Arguments PART_CATEGORY_ID Numeric 0 Pass in the part category id number. This is corporation-specific and needs to be looked up using the getAllPartsCategories method. Later on in the system, this is how everything is categorized in the sales & profit reports, the P&L, and other financials. Yes
Arguments PART_ID Numeric 0 Pass in the part id number. This is the system-assigned auto id number for the item or part. This is very important; it's how the whole line item gets tied in and is the purpose for adding the line item. This number ties it to the correct inventory item.

Also, by way of a note, if you are doing both parent and sub inventory, you will also need to make a call to the addEditSubInventory method (only if you are dealing with subs). Both methods need this part_id argument. Just a heads up. 		Yes
Arguments PART_NUMBER String Pass in the part number. This is the user-assigned or the human readable number for an item. This is how people can look items up. This should match the same case and spelling. Yes
Arguments STATE_TAX Numeric 0 Pass in the state tax for the line item. As a note, there are numerous tax fields. Please check to see what way your corp wants to account for them. There are city, state, county, and five custom fields for taxes. As a side note, internally if there is a rounding error, it is shown and passed into this column. No
Arguments STOCK Numeric 0 Pass in a stock number if applicable. Use 0 if not applicable. As a note, a stock unit is a big ticket item like a vehicle, trailer, house, gun, or some other serialized item. No
Arguments STORE_ID Numeric 0 Pass in the store or location id number. This value is corporation specific and can be looked up by going to the getGeneralLookupValues method. You'll be looking for the QRY_LOCATION_INFO_ARRAY data. This is a huge part of how we track quantities per location. If you have multiple locations, this is extremely important. Yes
Arguments TAX_CATEGORY_ID Numeric 2 Pass in the tax category id number. Default is 2 (2=taxable). These id numbers can be found by using the getLookUpValues method. Make sure to pass in the table name as tax_categories. As a side note, if you're using With Tax Included, make sure that it gets flipped to a normal taxable value here on the invoice line items. Basically, the With Tax Included setting is only used to figure out the taxes, and then it is set as physical taxable for database storage. The method used to calculate taxes is calculateTaxes. Yes
Arguments UNIT_OF_MEASUREMENT_ID Numeric 1 Pass in the unit of measurement id number. Default is 1 (1=each). These id numbers can be found by using the getLookUpValues method. Make sure to pass in the table name as units_of_measurement and the optional param as your corp id. Yes
Arguments USE_IN_LINE_DISCOUNT Numeric 0 Pass in a 1 for yes and a 0 for no. No
Arguments VENDOR_PAYEE_ID Numeric 0 Pass in the vendor id number. This is the vendor id number that's tied to the specific part or item number. This is required for database look ups later on. Vendor information can be found from other part number look ups. Yes


Results
RET_STATUS RET_MAIN_MESSAGE RET_SECOND_MESSAGE Redirect Link Description
ok Successfully added the invoice line item. [invoice line items] This assumes that everything went well.
dataIn Unable to add the invoice line item. Missing some data. Use your back button and try again. This is returned if the corp id, customer id, inventory type id, invoice number, invoice type id, part category id, part id, store id, tax category id, unit of measurement id, or vendor payee id arguments could not be found.
dataIn2 Unable to add the invoice line item. Missing the date stamp. Use your back button and try again. This is returned if the date is not valid.
decimalValue Unable to add the invoice line item. One or more values is over the maximum. See note below. One or more of the values is over +/- 99,000,000 (+/- ninety-nine million). Check the values (including any math) and try again. You may need to break the items into smaller parts or pieces. This is returned if the quantity, cost, price, percentage, etc. is too long.
db Unable to connect to the database. The invoice line item was not added to the database. Use your back button and try again. This is returned if there was an error in inserting or querying values such as in line discount, city tax, corp id, customer id, line quantity, other tax, part id, part number, po number, invoice type id, etc. There are about 50 values here.


Samples
Caption Text
JSON
{"API_CALL_FUNCTION_NAME": "addInvoiceLineItem","CORP_ID": 53,"CUSTOMER_ID": 449686,"INVENTORY_TYPE_ID": 5,"INVOICE_NUMBER": 78,"INVOICE_TYPE_ID": 2,"PART_CATEGORY_ID": 3114,"PART_ID": 248258,"STORE_ID": 178,"TAX_CATEGORY_ID": 2,"UNIT_OF_MEASUREMENT_ID": 1,"VENDOR_PAYEE_ID": 33018,"LINE_ITEM_DATE": "2016-03-24","CITY_TAX": 0.01,"COUNTY_TAX": 0.01,"DISCOUNT_CAMPAIGN": "Test Sale","INLINE_DISCOUNT_EXTENDED": 123.00,"INLINE_DISCOUNT_PER_LINE" :456.00,"INLINE_DISCOUNT_PERCENTAGE": 12.00,"ITEM_COST": 10.00,"ITEM_PRICE": 12.00,"LINE_DESCRIPTION": "Description Goes Here","LINE_ITEM_SORT": 100,"LINE_QUANTITY": 5.00,"LINE_RFID_TAG_NUMBER": "Tag123","LINE_SHOW": 1,"ORIGINAL_LIST_PRICE": 8.00,"OTHER_TAX_1": 0.01,"OTHER_TAX_2": 0.01,"OTHER_TAX_3": 0.01,"OTHER_TAX_4": 0.01,"OTHER_TAX_5": 0.01,"OUT_OF_AREA_TAX": 0.01,"PART_NUMBER": "Ptzl_carabiners","STATE_TAX": 0.01,"STOCK": 0,"USE_INLINE_DISCOUNT": 1,"API_CORP_KEY_ID": "PLA-0053","API_USER_NAME": "demo","API_USER_PASSWORD": "1234","API_CURRENT_PAYEE_ID": "3","API_INPUT_OUTPUT_TYPE": "JSON","API_URL_ENCODING": "AUTO"}