InvoiceItem

The InvoiceItem object represents an item added to an invoice. In EPASS, items are parts or accessories sold to customers or used by service technicians.
Tags:
Categories:

Add an Item to an Invoice

POST /invoicing/invoice/item/add

This endpoint adds an item to an open invoice. Items can’t be added to EPASS without an existing open invoice to add them to.

Invoice Conditions

An invoice must meet this list of conditions before you can add an item to it.

Condition Value
Invoice Status Invoice Status must be Open or Committed.
Branch Code Must be a valid Branch Code.
If not provided it will use the branch supplied during the login process, and if that is empty it uses the constant value DEFAULT.
Invoice JobStatus Any Job Status cascading that is configured in EPASS will be enforced through the API.
Bill To Customer BillToCustomer must be allowed to charge if the invoice is not an estimate and the payment type is AR.
Credit Limits will be enforced in the following situation:
- The invoice is not an estimate
- Credit Limit is enabled for the Customer
- The Invoice Payment Type is AR
- Require Credit Approval is disabled
- Either the Job Status is dispatchable or Dispatching is disabled completely

Payload

Required Fields

The following fields are the absolute minimum fields that should be required to add an item to an invoice.

Field Type Description
InvoiceCode string Must be a valid Invoice Code.
ItemCode string Must be a valid Item Code.
Item cannot be Obsolete if the Invoice Variables option Prevent Selling Obsolete Items/Models is True.
If not stock and the Invoice Variables option Warn When Selling Non-Stock Items/Models is True, we will return a warning message.
UserCreated string Must be a valid User Code that is not Obsolete. If not provided it will use the Login User.

ItemCode

If a valid ItemCode is provided then the following values will be defaulted from the Item. You can override any of the values that would come from the Item simply by providing your own value.

Key Value
ItemDesc Item -> Description
Tax2 Item -> Tax2
Tax3 Item -> Tax3
UnitCost If the Item.AverageCost is greater than 0, then Item.AverageCost otherwise LastCost

Potentially Required Fields

These fields may be required depending on your EPASS configuration, or there is unique behavior that needs to be mentioned.

Field Type Description
SellingPrice integer If the BillTo customer has a valid project code, then the SellingPrice cannot be less than the project price. If the Item has a valid sale price, then the SellingPrice cannot be less than the sale price.
ServiceTime integer This is the Item.Height.

addRelatedLines

Adding related detail lines can be controlled using the addRelatedLines object. If not provided then no related detail lines will be added.

Key Value Description
Comment Boolean Determines if related Comment lines are added
Misc Boolean Determines if related Misc lines are added

Calculated Fields

Key Value
Total If Status is Open and (Invoice is Estimate or (the Invoice Type option “Total open BO Lines” is True and the Invoice Variable option Automatic Back Order Items is True) or the Item Inventory Variable option Auto Commit Items In Invoicing is false) then the Total will be: SellingPrice.Value * QtyOrdered.Value
Otherwise, the Total will be: SellingPrice.Value * QtyShipped.Value
Status If Invoice is not an Estimate and the Item Variable Auto Commit is True and there is sufficient QOH in the Location then the item will be committed and the Status will be Committed.
Otherwise the status will be Open.

Sample: Adding an Item to an Invoice

 POST /invoicing/invoice/item/add

{
   "userCreated": null,
   "tripNo": null,
   "installed": null,
   "reference": null,
   "branchCode": null,
   "failureCode": null,
   "invoiceCode": "1234567",
   "itemCode": "item3",
   "locationCode": "001",
   "qtyOrdered": 1,
   "sellingPrice": 120,
   "supplierCode": null,
   "supplierInvoice": null,
   "supplierInvoiceDate": null,
   "taken": null,
   "takenDate": null,
   "tax2": null,
   "tax3": null
   "addRelatedLines": {
       "Misc": true,
       "Comment": true
   },
}

 {
    "success": true,
    "warning": false,
    "httpStatusCode": 201,
    "generalMessage": null,
    "exceptionMessage": null,
    "keys": [
        {
            "table": "InvoiceItem",
            "keys": [
                {
                    "key": "ID",
                    "fields": [
                        {
                            "fieldName": "ID",
                            "fieldValue": 123
                        }
                    ]
                }
            ]
        },
        {
            "table": "InvoiceAddress",
            "keys": [
                {
                    "key": "ID",
                    "fields": [
                        {
                            "fieldName": "ID",
                            "fieldValue": 11235
                        }
                    ]
                }
            ]
        },
        {
            "table": "InvoiceAudit",
            "keys": [
                {
                    "key": "ID",
                    "fields": [
                        {
                            "fieldName": "ID",
                            "fieldValue": 145678
                        }
                    ]
                }
            ]
        }
    ],
    "messages": [],
    "warnings": []
}



{
    "success": false,
    "message": "One or more of the fields has an invalid or missing value.",
    "lastException": null,
    "recordId": 0,
    "code": null,
    "httpStatusCode": 422,
    "messageDetails": [
        "Items are not allowed on Finished Invoices."
    ]
}