Add an Invoice Header

Tags:
Categories:

POST /invoicing/invoice/add

This endpoint creates an invoice header. You need to create the invoice header first before you can add items to the invoice, such as a model or payment.

Payload

Required Fields

The following are the absolute minimum fields required to create an invoice header.

Field Type Description
BillToCode string Must be a valid Customer Code.
Do Not Service must not be True for the customer.
If Financed is True the customer must be a Finance Company.
If the Payment option AR is true, then the BillTo Customer must allow charge.
Code string If not provided it will generated a Code using either the Invoice Type number or system numbering series.
InvTypeCode string Must be a valid Invoice Type Code that is not Obsolete.
PaymentTypeCode string Must be a valid Payment Type Code that is not Obsolete.
SoldToCode string Must be a valid Customer Code. Do Not Service must not be True for the customer.
Tax2Code string Must be a valid Tax Code.
If not provided the Tax Code from the Bill To Customer will be used.
Note: Tax2Perentage should be provided as well. If not provided then the Tax Percentage from the Tax Code (either the provided code or from the Customer) will be used.
UserCreated string Must be a valid User Code that is not Obsolete.
If not provided it will use the Login User.

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 Value
BranchCode string 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”.
If a valid Invoice Type is provided and the Invoice Type option “Always Use This Branch” is True then the Branch from the Invoice Type will be used.
Department string This is a required field.
If provided then it must be a valid Department for the Invoice Type that was provided.
If not provided then the Default Department from the Invoice Type will be used (as long as the Invoice Type Default Department from Terminal is not checked).
Otherwise it will be set to ALL.
DispatchUnits integer If a value is not provided and Dispatching is turned on for the Invoice Type, this value will default from Dispatching Variables - Default Call Units.
Field1 string If the Invoice Variables option Field1Mandatory is True, then Field1 is required.
Field2 string If the Invoice Variables option Field2Mandatory is True, then Field2 is required.
Field3 string If the Invoice Variables option Field3Mandatory is True, then Field3 is required.
Field4 string If the Invoice Variables option Field4Mandatory is True, then Field4 is required.
Field5 string If the Invoice Variables option Field5Mandatory is True, then Field5 is required.
JobStatusCode string If the Invoice Type option JobStatusRequired is True, then the JobStatusCode field must have a valid value.
Must be allowed for the provided Department.
Dispatchable Job Statuses are currently not allowed, as Routing is not yet supported.
MapZoneCode string If the Invoice Type option MapZoneRequired is True, then the MapZoneCode field must have a valid value.
Must be allowed for the provided Department.
Priorities array (string) If the Invoice Type option RequirePriorities is True, then the Priorities field must have at least one valid value.
Qualifications array (string) If the Invoice Type option RequireQualifications is True, then the Qualifications field must have at least one valid value.
Reference string If the Invoice Type option RequireReference is True, then the “Reference” field must have a valid value.
RequestedDate string Format: YYYY-MM-DDThh:mm:ss.sssZ
If the Invoice Type options RequestedDateRequired is True and NotShowRequestedDate is False, then the RequestedDate field must have a valid value.
SaleReferralCode string If the Invoice Type option SaleReferralRequired is True, then the SaleReferralCode field must have a valid value.
Salesperson1Code string If the Invoice Type option RequireSalesperson is True then it is required.
Must be a valid Salesperson Code that is not Obsolete.
Must be allowed for the provided Department.
ScheduleDate and PickUpDate string Format: YYYY-MM-DDThh:mm:ss.sssZ
If the Invoice Type option LinkTaxesToDeliveryPickup is True then either ScheduleDate or PickupDate will be required (you are not allowed to provide both dates).
If the Invoice Type option ScheduleOrPickupRequired is True then either ScheduleDate or PickupDate will be required.
If the Invoice Type option SchedAndPickupDtAllowed is True then you will be allowed to provide both a ScheduleDate and a PickupDate (unless LinkTaxesToDeliveryPickup is also True), otherwise you are only allowed to provide one of these dates.
ServiceTime integer This is the Units for the invoice multiplied by Minutes Per Unit (from Dispatching variables). Note: If Accumulate Points for Call Units is turned ON it will always return 0.
ShipViaCode string If the Invoice Type option RequireShipVia is True, then the ShipViaCode field must have a valid value.
SoldToAddress1 string If the Invoice Type option UseTTRTax is True AND PickUpDate is empty, then SoldToAddress is required.
SoldToCity string If the Invoice Type option UseTTRTax is True AND PickUpDate is empty, then SoldToCity is required.
SoldToDirections string If the VarAR option RequireDirections is True, then SoldToDirections is required.
SoldToEmail string If the VarAR option RequireEmail is True or the Invoice Type option RequireEmailDuringAddInvoice is True, then SoldToEmail is required.
SoldToState string If the Invoice Type option UseTTRTax is True AND PickUpDate is empty, then SoldToState is required.
SoldToZipCode string If the Invoice Type option UseTTRTax is True AND PickUpDate is empty, then SoldToZipCode is required.
SvcBrandCode string If the Invoice Type option RequireServiceBrand is True, then the SvcBrandCode field must have a valid value.
SvcComplaintDesc string If the Invoice Type option RequireServiceComplaint is True, then the SvcComplaintDesc field must have a value.
SvcDatePurchased string Format: YYYY-MM-DDThh:mm:ss.sssZ
If the Invoice Type option RequireServicePurchaseDate is True then SvcDatePurchased is required.
SvcDealerCode string If the Invoice Type option RequireServiceDealer is True, then the SvcDealerCode field must have a valid value.
SvcFollowUpDate string Format: YYYY-MM-DDThh:mm:ss.sssZ
If a value is not provide and if the Invoice Type option Enable Follow Up date is True then this will be set to Today + the Default Follow Up Days from the Invoice Type.
SvcModel string If the Invoice Type option RequireServiceModel is True, then the SvcModel field must have a valid value.
SvcProduct string If the Invoice Type option RequireServiceProduct is True, then the SvcProduct field must have a valid value.
SvcSerial string If the Invoice Type option RequireServiceSerial is True, then the SvcSerial field must have a valid value.
SvcSpecAuthNumber string If SvcBrandCode has RequiresSpecialAuth set to True, SvcSpecAuthNumber is required.
Table1 string If the Invoice Type option Table1Mandatory is True, then the Table1 field must have at least one valid value.
Table2 string If the Invoice Type option Table2Mandatory is True, then the Table2 field must have at least one valid value.
TripChargeCode string If the Invoice Type option RequireTripCharge is True, then the TripChargeCode field must have a valid value.

Sold to Customer

If a valid SoldToCode is provided then the following values will be defaulted from the Customer. You can override any of the values that would come from the Customer simply by providing your own value, or a “blank” value if you do not want to use the Customer.

Key Value
PONumber Customer -> PONumber ** Unless Customer PO Number has expired.
SoldToAddress1 Customer -> Address1
SoldToAddress2 Customer -> Address2
SoldToBusinessPhone Customer -> BusinessPhone
SoldToBusinessPhoneTextEnabled Customer -> BusinessPhoneTextEnabled
SoldToCity Customer -> City
SoldToDeclineEmail Customer -> DeclineEmail
SoldToDirections Customer -> Directions
SoldToEmail Customer -> Email
SoldToFax Customer -> Fax
SoldToFaxTextEnabled Customer -> FaxTextEnabled
SoldToFirstName Customer -> FirstName
SoldToLastName Customer -> LastName
SoldToLatitude Customer -> Latitude
SoldToLongitude Customer -> Longitude
SoldToPhone1 Customer -> Phone1
SoldToPhone1TextEnabled Customer -> Phone1TextEnabled
SoldToPhone2 Customer -> Phone2
SoldToPhone2TextEnabled Customer -> Phone2TextEnabled
SoldToPreferredContact Customer -> PreferredContact
SoldToState Customer -> State
SoldToSuite Customer -> Suite
SoldToZipCode Customer -> ZipCode
updateSoldToCustomerOnFile If you would like to update the Customer record with the provided Sold To values then you can specify True for this value.

BillToCustomer

If a valid BillToCode is provided then the following values will be defaulted from the Customer. You can override any of the values that would come from the Customer simply by providing your own value, or a “blank” value if you do not want to use the Customer.

Key Value
BillToAddress1 Customer -> Address1
BillToAddress2 Customer -> Address2
BillToBusinessPhone Customer -> BusinessPhone
BillToBusinessPhoneTextEnabled Customer -> BusinessPhoneTextEnabled
BillToCity Customer -> City
BillToEmail Customer -> Email
BillToFax Customer -> Fax
BillToFaxTextEnabled Customer -> FaxTextEnabled
BillToFirstName Customer -> FirstName
BillToLastName Customer -> LastName
BillToPhone1 Customer -> Phone1
BillToPhone1TextEnabled Customer -> Phone1TextEnabled
BillToPhone2 Customer -> Phone2
BillToPhone2TextEnabled Customer -> Phone2TextEnabled
BillToPreferredContact Customer -> PreferredContact
BillToState Customer -> State
BillToSuite Customer -> Suite
BillToZipCode Customer -> ZipCode
ItemListPriceCode Customer -> ItemListPriceCode
LaborRate Customer -> LaborRate
OtherListPriceCode Customer -> OtherListPriceCode
SerialListPriceCode Customer -> SerialListPriceCode
updateBillToCustomerOnFile If you would like to update the Customer record with the provided Bill To values then you can specify True for this value.

Sample: Adding an Invoice

 
  POST /invoicing/invoice/add {
    "shipViaCode": "ABC Delivery",
    "billToCode": "11111",
    "branchCode": "01",
    "invTypeCode": "RE",
    "jobStatusCode": "UNCONFIRMED",
    "mapZoneCode": "ON",
    "saleReferralCode": "Online",
    "salesperson1Code": "99999",
    "scheduleDate": "2021-11-10",
    "soldToCode": "123456",
    "tax2Code": "ABC",
    "userCreated": "1138",
    "updateSoldToCustomerOnFile": false,
    "updateBillToCustomerOnFile": false,
    "priorities": ["PM", "3MAN"],
    "qualifications": ["GS"],
    "inFulfillment": true,
    "relatedInvoiceCodes": [
        {
            "relatedInvoiceCode": "123456789",
            "relation": "LINKED"
        }
    ]
} 
  
 {
    "success": true,
    "warning": false,
    "httpStatusCode": 201,
    "generalMessage": null,
    "exceptionMessage": null,
    "keys": [
        {
            "table": "Invoice",
            "keys": [
                {
                    "key": "ID",
                    "fields": [
                        {
                            "fieldName": "ID",
                            "fieldValue": 123456
                        }
                    ]
                },
                {
                    "key": "PrimaryKey",
                    "fields": [
                        {
                            "fieldName": "Code",
                            "fieldValue": "           123456789"
                        }
                    ]
                }
            ]
        },
        {
            "table": "InvoiceRelations",
            "keys": [
                {
                    "key": "ID",
                    "fields": [
                        {
                            "fieldName": "ID",
                            "fieldValue": 123456
                        }
                    ]
                }
            ]
        }
    ],
    "messages": [],
    "warnings": []
}

  
 {
    "success": false,
    "warning": false,
    "httpStatusCode": 422,
    "generalMessage": "One or more of the fields has an invalid or missing value.",
    "exceptionMessage": null,
    "keys": [],
    "messages": [
        {
            "code": "INV-010041",
            "message": "SoldToCode is required."
        }
    ],
    "warnings": []
}