Weborder

The Weborder endpoint can be used to send product orders collected from an online shopping cart to EPASS.
Tags:
Categories:

The Weborder endpoint requires some initial setup within EPASS before it can be used. See the EPASS Setup instructions for more details.

Add a Web Order

POST /external/weborder

This endpoint adds a web order to the EPASS Web Order Queue. Once the order is in the queue, it needs to be reviewed and processed within EPASS.

Payload

Field Type Description Max Length Required
webOrderID string This must be a unique ID that has not been used for a previous web order. 20
orderDate string Format: YYYY-MM-DD
The order date.		 10
orderComment string Customer notes. 8000
grandTotal integer The invoice’s grand total.
lastName string The last name of the person placing the order. 50
firstName string The first name of the person placing the order. 20
email string The email of the person placing the order. 255
shippingMethod string Shipping method. 50
carrierCode string Shipping carrier code, such as ‘FEDEX’ or ‘UPS.’ 5
trackingNumber string Shipping tracking number. 250
shippingETA string Format: YYYY-MM-DD
Shipping estimate date (from carrier.)		 10
subTotal integer Invoice total, excluding tax, shipping charges, and discounts.
taxAmount integer Total tax.
shippingAmount integer Total shipping charges.
discountAmount integer Total of all discounts.
shipToLastName string The recipient’s last name. (See Note) 50
shipToFirstName string The recipient’s first name. (See Note) 20
shipToEmail string The recipient’s email. 255
shipToAddress1 string The recipient’s street address. 30
shipToAddress2 string The recipient’s street address (continued) 30
shipToCity string The recipient’s city. 30
shipToState string The recipient’s state or province. 4
shipToZip string The recipient’s zip or postal code. 10
shipToCountry string The recipient’s country. 30
shipToPhone1 string The recipient’s primary phone number. 20
shipToPhone2 string The recipient’s' secondary phone number. 20
shipToCompanyName string The recipient’s company name (if applicable. See Note.) 50
shipToFax string The recipient’s fax number. 20
billToLastName string The buyer’s last name. (See Note) 50
billToFirstName string The buyer’s first name. (See Note) 20
billToAddress1 string The buyer’s street address. 30
billToAddress2 string The buyer’s street address (continued). 30
bilToCity string The buyer’s city. 30
billToState string The buyer’s state or province. 4
billToZip string The buyer’s zip or postal code. 10
billToCountry string The buyer’s country. 30
billToEmail string The buyer’s email. 255
billToPhone1 string The buyer’s primary phone number. 20
billtToPhone2 string The buyer’s secondary phone number. 20
billToCompanyName string The buyer’s company name (if applicable. See Note.) 50
billToFax string The buyer’s fax number. 20
deliveryPickup string Format: YYYY-MM-DD
The delivery/pickup date of the web order.		 10
requestedDate string Format: YYYY-MM-DD
The requested date of the web order.		 10

Web Order Details

These arrays are used to add products, payments, and charges to the web order, such as models, installations, and miscellaneous charges. Each array is optional and not required, and not all parameters within each array are mandatory.

Installs [ ]

Adds an installation to the web order.

Field Type Description Max Length Required
installCode string The installation code. 20
installDesc string The description of the installation. 50
qty integer The number of installations added to the web order.
price integer The installation price.

Example

...
"Installs": [
        {
            "installCode": "DISHINSTALL",
            "InstallDesc": "Full dishwasher installation.",
            "qty": 1,
            "price": 99.95
        }

Miscs [ ]

Adds a miscellaneous charge to the web order.

Field Type Description Max Length Required
miscNumber string The miscellaneous charge code. 15
miscDesc string The description of the miscellaneous charge. 30
qty integer The number of miscellaneous charges added to the web order.
price integer The amount of the miscellaneous charge.

Example

...
"Miscs": [
        {
            "miscNumber": "1138",
            "miscDesc": "Removal fee",
            "qty": 1,
            "price": 19.95
        },

Models [ ]

Adds a model to the web order.

Field Type Description Max Length Required
modelNumber string The model ID code. 20
modelDesc string The model’s description. 50
qtyPurchased integer The number of models purchased and added to the web order.
qtyShipped integer The number of models that need to be shipped.
qtyCancelled integer The number of models cancelled that need to be removed from the order.
price integer The model’s individual selling price.

Example

...
"Models": [
        {
            "modelNumber": "1138",
            "modelDesc": "Stainless Steel Dishwasher",
            "qtyPurchased": 2,
            "qtyShipped": 2,
            "qtyCancelled": 0,
            "price": 649.99
        },

Payments [ ]

Adds a payment to the web order.

Field Type Description Max Length Required
paymentMethod string The payment method. “Cash,” “MasterCard,” and “check” are examples of payment methods. 5
note string The payment note. 30
amount integer The payment amount.

Example

  "Payments": [
        {
            "paymentMethod": "VISA",
            "note": "Auth# 1234567",
            "amount": 12.03
        },

Wtys [ ]

Adds a warranty product to the order.

Field Type Description Max Length Required
wtyCode string The warranty ID code. 15
wtyDesc string The warranty’s description. 50
months integer The warranty term.
price integer The price of the warranty product.
modellines[] array Adds model lines to the order for each warranty product. See ModelLines[].

Example

 "Wtys": [
        {
            "wtyCode": "1YREXTWRTY",
            "wtyDesc": "1 YR Extended Warranty",
            "months": 24,
            "price": 100.00
        },

ModelLines[ ]

Associates the warranty codes with the models in the web order.

Field Type Description Max Length Required
modelCode string The model code associated with the warranty. 20
serialCode string Serial code associated with the warranty. 20
sellingPrice integer Original selling price of the model/serial associated with the warranty.
Example
 "Wtys": [
      {
        "wtyCode": "1YREXTWRTY",
        "wtyDesc": "1 YR Extended Warranty",
        "months": 24,
        "price": 100.00,
        "modellines": [
            {
                "modelCode": "WRQA59CNKZ",
                "serialCode": "00001",
                "sellingPrice": 3418.64
            }   
        ]
        }

Sample: Adding a Web Order


POST /external/weborder
{
    "webOrderId": "9010",
    "orderDate": "2022-11-27",
    "shippingMethod": null,
    "carrierCode": "",
    "trackingNumber": "tracking Number",
    "shippingETA": "2021-11-27",
    "subTotal": 0,
    "taxAmount": 0,
    "shippingAmount": 0,
    "discountAmount": 0,
    "grandTotal": 0,
    "orderComment": "order Comment",
    "lastName": "Nelson",
    "firstName": "James",
    "email": "Email@epasstest.com",
    "shipToLastName": "Nelson",
    "shipToFirstName": "James",
    "shipToEmail": "ShipEmail@epasstest.com",
    "shipToAddress1": "600 25th Street",
    "shipToAddress2": "ShipAddr2",
    "shipToCity": "ShipCity",
    "shipToState": "BC",
    "shipToZip": "Ship111",
    "shipToCountry": "CA",
    "shipToPhone1": "ShipPh1",
    "shipToCompanyName": "ShipToCompany",
    "billToFirstName": "BillJoe",
    "billToLastName": "ShipDoe",
    "billToAddress1": "ShipAddr1",
    "billToAddress2": "ShipAddr2",
    "billToCity": "ShipCity",
    "billToState": "BC",
    "billToZip": "N4W 0Y2",
    "billToCountry": "CA",
    "billToPhone1": "BillPh1",
    "billToPhone2": "BillPh2",
    "billToFax": "BillFax",
    "billToEmail": "Billemail@epasstest.com",
    "billToCompanyName": "BillCompany",
    "cancelReason": "",
    "deliveryPickup": "2021-06-15",
    "requestedDate": "2021-06-15",
    "tax2Code": "",
    "tax3Code": "",
    "branchCode": "",
    "Installs": [
      {
        "installCode": "install Code",
        "InstallDesc": "Install Desc",
        "qty": 5,
        "price": 6.03
      },
      {
        "installCode": "install Code1",
        "installDesc": "Install Desc1",
        "qty": 8,
        "price": 9.03
      }
    ],
    "Miscs": [
      {
        "miscNumber": "misc Number1",
        "miscDesc": "misc Desc1",
        "qty": 5,
        "price": 6.03
      },
      {
        "miscNumber": "misc Number2",
        "miscDesc": "misc Desc2",
        "qty": 6,
        "price": 7.03
      }
    ],
    "Payments": [
      {
        "paymentMethod": "C",
        "note": "Note1",
        "amount": 12.03
      },
      {
        "paymentMethod": "EFT",
        "note": "Note2",
        "amount": 22.03
      }
    ],
    "Models": [
      {
        "modelNumber": "WRQA59CNKZ",
        "modelDesc": "36 FOUR DOOR FRIDGE, 19.4 CU FT, SS",
        "qtyPurchased": 1,
        "qtyShipped": 0,
        "qtyCancelled": 0,
        "price": 2344.76
      },
      {
        "modelNumber": "RF30BB6200QLAA",
        "modelDesc": "36 FRENCH DOOR, ICE, WATER, SS PANELS",
        "qtyPurchased": 1,
        "qtyShipped": 0,
        "qtyCancelled": 0,
        "price": 2404.29
      }
    ],
    "Wtys": [
      {
        "wtyCode": "1YREXTWRTY",
        "wtyDesc": "1 YR Extended Warranty",
        "months": 24,
        "price": 100.00,
        "modellines": [
            {
                "modelCode": "WRQA59CNKZ",
                "serialCode": "00004",
                "sellingPrice": 2344.76
            }   
        ]
        },
        {
      "wtyCode": "1YREXTWRTY",
      "wtyDesc": "1 YR Extended Warranty",
      "months": 24,
      "price": 100.00,
      "modelLines": [        
        {
          "modelCode": "RF30BB6200QLAA",
          "serialCode": "00001",
          "sellingPrice": 2404.29
        }
      ]
        } 
    ]
  }



{
    "Success": true,
    "Warning": false,
    "HttpStatusCode": 201,
    "GeneralMessage": null,
    "ExceptionMessage": null,
    "Keys": [
        {
            "Table": "WebOrder",
            "Keys": [
                {
                    "Key": "ID",
                    "Fields": [
                        {
                            "FieldName": "ID",
                            "FieldValue": 11304
                        }
                    ]
                }
            ]
        },
        {
            "Table": "InvoiceWebOrderModel",
            "Keys": [
                {
                    "Key": "ID",
                    "Fields": [
                        {
                            "FieldName": "ID",
                            "FieldValue": 11047
                        }
                    ]
                }
            ]
        },
        {
            "Table": "InvoiceWebOrderModel",
            "Keys": [
                {
                    "Key": "ID",
                    "Fields": [
                        {
                            "FieldName": "ID",
                            "FieldValue": 11048
                        }
                    ]
                }
            ]
        },
        {
            "Table": "InvoiceWebOrderPayment",
            "Keys": [
                {
                    "Key": "ID",
                    "Fields": [
                        {
                            "FieldName": "ID",
                            "FieldValue": 11301
                        }
                    ]
                }
            ]
        },
        {
            "Table": "InvoiceWebOrderPayment",
            "Keys": [
                {
                    "Key": "ID",
                    "Fields": [
                        {
                            "FieldName": "ID",
                            "FieldValue": 11302
                        }
                    ]
                }
            ]
        },
        {
            "Table": "InvoiceWebOrderWty",
            "Keys": [
                {
                    "Key": "ID",
                    "Fields": [
                        {
                            "FieldName": "ID",
                            "FieldValue": 1057
                        }
                    ]
                }
            ]
        },
        {
            "Table": "InvoiceWebOrderWtyModelLines",
            "Keys": [
                {
                    "Key": "ID",
                    "Fields": [
                        {
                            "FieldName": "ID",
                            "FieldValue": 779
                        }
                    ]
                }
            ]
        },
        {
            "Table": "InvoiceWebOrderWty",
            "Keys": [
                {
                    "Key": "ID",
                    "Fields": [
                        {
                            "FieldName": "ID",
                            "FieldValue": 1058
                        }
                    ]
                }
            ]
        },
        {
            "Table": "InvoiceWebOrderWtyModelLines",
            "Keys": [
                {
                    "Key": "ID",
                    "Fields": [
                        {
                            "FieldName": "ID",
                            "FieldValue": 780
                        }
                    ]
                }
            ]
        }
    ],
    "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": "WebOrder-00032",
            "Message": "Invalid Serial Code Under Warranty (exceeded character length)."
        }
    ],
    "Warnings": []
}

Search for a Web Order

POST /external/weborder/search

This endpoint searches and returns a web order. You can search for a web order by any of it’s attributes.


POST /external/weborder/search
{
    "query": {
        "fieldName": "WebOrderID",
        "eval": "EQUAL",
        "value": "9001"
    }
}


POST /external/weborder/search
{
    "paging": {
        "pageSize": 5,
        "pageStartId": 0
    },
    "query": {
            "fieldName": "DateRequested",
                "eval": "between",
                "start": "10/10/2020",
                "end":"10/10/2022"
    }, 
    "subquery":[
        {
            "logic": "and",
            "query": {
                "fieldName": "CITY",
                "eval": "IN",
                "valueList": ["vancouver","calgary","burnaby"]
            },
            "subquery":[
            {
                "logic": "or",
                "query": {
                    "fieldName": "Zip",
                    "eval": "equal",
                    "value": "123"
                } 
            }
            ]
        },
        {
            "logic": "or",
            "query": {
                "fieldName": "DatePurchased",
                "eval": "between",
                "start": "10/10/2020",
                "end":"10/10/2021"
            },
            "subquery":[
            {
                "logic": "and",
                "query": {
                    "fieldName": "LastName",
                    "eval": "like",
                    "value": "A"
                } 
            }
            ]
        },
        {
            "logic": "and",
            "query": {
                "fieldName": "email",
                "eval": "equal",
                "value": "test@test.com"
            }
        },
        {
            "logic": "or",
            "query": {
                "fieldName": "phone1",
                "eval": "equal",
                "value": "60411111111"
            }
        }
    ],
    "tables": {
        "ServiceRequest": [
            "ID",
            "Code",
            "FirstName",
            "LastName",
            "city",
            "email",
            "phone1" 
        ] 

    },
    "extendedInfo": {
        "Brand": [
            "ID",
            "Code",
            "Description"
        ],
          "Dealer": [
            "ID",
            "Code",
            "Description"
        ],
          "Product": [
            "ID",
            "Code",
            "Description"
        ]
    }
}

EPASS Setup Instructions

Before using the Weborder endpoint, you’ll need to perform two setup steps in EPASS: create a misceallaneous charge code and activate security options for the User or Group that will view and process web orders.

Create a Miscellaneous Charge Code

Data that is passed to EPASS through the Weborder endpoint isn’t validated. This allows flexibility when using the Weborder endpoint as your storefront can sell product that you may not regularly keep in stock or have a record for in EPASS. EPASS processes web orders with these unique products by assigning them a miscellaneous charge code during order processing. This code must be created in EPASS before web orders can be processed.

To Create the Miscellaneous Charge Code

  1. In EPASS, go to Tools > System Maintenance.

  2. In the Tables tab, select Miscellaneous, and then click Open.

  3. Click Add.

  4. Do the following:

    • Enter XXX in the Code field.
    • Enter a Description (for example, ‘Invalid Codes’)
    • Select an account from the G/L Revenue dropdown.
    • Select the Do Not Finish checkbox.

  5. Click OK, and then exit the Miscellaneous Charge window.

Now when web orders are processed, any models or items that don’t have a record entry in EPASS are assigned the XXX miscellaneous charge.

Enable EPASS Security Options

EPASS Users and Groups require three security options to view, process, and cancel web orders.

To Enable Web Order Security Options:

  1. In EPASS, go to Tools > System Maintenance.

  2. In the Tables tab, select User Security, and then click Open.

  3. Select a User or Group, and then click Security.

  4. In the Keyword search, enter Web Order.

  5. Select the required Web Order security options, and then click OK.

  6. Exit the User Security window.