eCommerce API Library

Overview

The eCommerce API is new to version 15.05. The below information, which is listed based on the DEACOM version the APIs are made available, can be sent to the customer's Design team for use to properly configure an eCommerce site. For each API call listed below, two example responses are included - one for a success and one for a failure. The process described in this page essentially negates the existing eCommerce Functional Guides. In all calls listed, when "localhost" is specified, insert the appropriate IP address in its place.

SessionID Implementation

As of build 15.05.016, SessionID Tokens will be used in API calls. Pertinent information that was previously passed in via API, such as Bill-To ID and User ID, are no longer required as that information is tied to the SessionID Token.

At a high level, the process is as follows:

  • Credentials – User accounts and credentials are managed through the ERP. Each user account can be linked to new or existing Bill-To / Ship-To records, and has a unique set of credentials.
  • Authentication – In order to communicate with the eCommerce APIs, valid user credentials must be passed to the service first. Successful authentication will return an authenticated SessionID token. Multiple SessionIDs can exist at a time. Each session of a user of the eCommerce should have its own authenticated SessionID.
  • Usage – Once an authenticated SessionID token has been procured, that token must be passed to all subsequent API calls for that user to tell the server who is currently transacting. Pertinent information that was previously passed in via API, such as Bill-To ID and User ID, are no longer required as that information is tied to the SessionID Token.

Why – This model does a few things:

  • Simplifies calls and removes potential errors with mismatched / wire crossed IDs since carts, billing information, and user information is all tightly coupled with a session token.
  • Enforces good security practices, removing the potential for brute force attacking with random Bill-to or User IDs to compromise the ERP.
  • Unification of code. This is actually the same session system that our ERP uses (we simply functionalized it), and has proven to provide proper data isolation and allowance of a high number of concurrent, active users.

Details of how SessionIDs are generated and used are as follows:

The backbone of this functionality now lies with a session token. Every API call in DEACOM is initiated with a session token that tells the user which active session this call should be attributed to. Whereas the calls previously required UserIDs/CartIDs to be specified, this new approach keeps a session token persistent between a series of calls. Each session would be linked to a user and/or cart and any attempt to access a call without a session would be denied; a malicious attempt by an outside source to access customer information, using User/GetData for example, would not be able to spam arbitrary UserIDs to get personal customer data without an authenticated session token. Session tokens are unique and infinite session tokens can be perpetuated at a time.

The process of acquiring a token is accomplished through the User/Login function. After a successful login, a SessionID token will be assigned and returned as a cookie. Then, that token will be retained and passed as a header parameter (POST, GET, or COOKIE all work) for all subsequent calls for that user’s eCommerce session until logging out. For example, after logging a user in, a new cart can be created for that user (without the need to pass in a UserID), which would also track a Cart in the session from that point on. With the User and Cart now linking directly to the session, all APIs which previously required UserID or CartID no longer require them. For example, User/ChangeBillTo(int UserID, int BillToID) is now just User/ChangeBillTo(int BillToID), as the UserID that was previously required is now accessible through the session. While this will mean existing API calls will need to be modified, the result is a more secure way of handling data to prevent unapproved access.

Note: Beginning in version 16.04.108, carts are now deleted from database storage after 48 consecutive hours of inactivity. This is necessary for the prevention of database bloat, as carts were previously stored indefinitely. The user can resume their shopping session at any time within the time limit to reset the 48 hours of grace time before the cart is deleted.

Configuration

To use the eCommerce API, an eCommerce Site must first be added in DEACOM. The resulting cs_id generated must then be added as a Header in your environment. To complete this configuration, follow the steps below:

  1. Create a new eCommerce Site via Tools > Maintenance > eCommerce Sites.
  2. On the eCommerce Sites form, modify the grid layout to include the cs_id field by following the process steps of the Configuring Grid Layouts and Automated Reports page.
  3. Close and re-open the eCommerce Sites form so that the new column appears and displays the new Site's ID. Take note of this value.
  4. In your environment, navigate to the Headers tab. Enter a variable called "SiteID" in the Key column and the value from step 3 in the Value column.

Notes:

If companies wish to allow customers the ability to add items with 0 on hand quantity to their cart(s), then the "Use MRP For On Hand Quantities" flag via Tools > Maintenance > eCommerce Sites must be unchecked. This allows items to be added to the cart and purchased regardless of quantity available.

Versions 16.04.108 and 16.04.112 have enhanced the process to setup email reminders. Companies may wish to contact their ECI/Deacom support or implementation team for guidance in this area. The details for setup are indicated below.

Version 16.04.108 enhancements:

  • Custom images are now supported in the cart reminder text, via the new <imagefile> tag. This tag can be used on an image file name. The picture will be placed in the email where the tag is placed if the image file name exists in the "dmpict" table.
  • Custom subjects are now supported in the cart reminder text, via the new <subject> tag. The content in this tag will be used as the subject of the email.
  • An HTML table will automatically be added to the reminder email, containing pictures and descriptions of the products that were left in the abandoned cart. This table is stylized to render well across email clients and on mobile.
  • Images are now placed on cart reminder emails via invisible attachments. These invisible attachments are referenced as the sources of the image files. This prevents the email from bloating in size due to inline Base64.
  • Descriptions for eCommerce products in the email are now pulled from the "u_ecomm_description_memo" UDF on the Item Master, if it exists. If it does not exist, the description is pulled from the Item Master's "Description" field instead.

Version 16.04.112 enhancement:

  • Users can define how long before a reminder email is sent via the "Cart Reminder Email Min." field on the Edit eCommerce Site form.

Version 16.04.126 enhancement:

New types of product sorting are now possible. This includes alphabetical order, best selling, and price (with the ability to specify a price range if desired).

Model/Code Structure Details

Multiple APIs may use the same models, which are called code structure. Examples of these models and their details, togather with the APIs they impact are listed below.

CartModel

Contains details and properties dealing with any item added to a cart.

The "SalesUnit" property in this model allows the showing of the Unit of Measure on the cart items. (The system will obtian the pr_id (item ID) from the cart item, then reference the sales unit (pr_salunid) for that item, and finally return the un_name corresponding to the pr_salunid.

The OrderType(string) property is available to the CartModel to support the ability to creat orders by different types by adding a the ability to override the logically determined order type in Cart/Checkout/ by providing an argument for an optional parameter.

OrderHistoryModel

Contains details and properties dealing with the changes (items added/remvoed, quantaties modified, and header changes) for the specified order.

The "InvoiceStatus" property, similar to "ShippingStatus" is used to calculate this property. - - if <order>.to_invdate== null ? "Not Invoiced" : Invoiced

The "PaymentStatus" property is available - - * if <order>.to_paydate == null ? "Not Paid" : Paid , - to_dueship: pull to_dueship for this order , - to_shipped: pull to_shipped for this order

eCommerce and Foreign Currencies

  • Beginning in version 17.01.053, all API endpoints that report currency information will now display a node in the returned JSON that clarifies which currency is being used.
  • This data has been added to the returned JSON for User/GetOrder, BillTo/GetData, BillTo/StatelessGetData, ShipTo/GetData, and ShipTo/StatelessGetData.
  • All API endpoints which create a User, Bill-To, or Ship-To now have a "CurrencyID" parameter that allows for a currency to be assigned on that new object. This applies to User/Register, BillTo/Create, BillTo/StatelessCreate, ShipTo/Create, and ShipTo/StatelessCreate.
  • Additionally, all instances in eCommerce where a currency object is involved in a transaction will now pull the currency type that is assigned on the current user's Bill-To Company.

Process

To begin using the below API calls, the SiteID (configured in DEACOM) must be passed in as a Header variable (refer to the Configuration section for more information) and SessionID must be passed in the cookies. In all calls listed, when "localhost" is specified, insert the appropriate IP address in its place. Be sure to use the proper IP address, otherwise calls will not execute and the below error will be received. In addition, any time a password is specified in a call, it must be encrypted or the call will not work. Passwords in the below examples are displayed in plain text for demonstration purposes.

Could not get any response

  • There was an error connecting to http://localhost:8080/Cart/Create.

Why this might have happened:

  • The server couldn't send a response: Ensure that the backend is working properly
  • Self-signed SSL certificates are being blocked: Fix this by turning off 'SSL certificate verification' in Settings > General
  • Proxy configured incorrectly: Ensure that proxy is configured correctly in Settings > Proxy
  • Request timeout: Change request timeout in Settings > General

Setting Database IDs When Using Multiple Company Databases

Setting via Header Value

Beginning in version 16.00.096 an optional header paramater, DatabaseID, has been made available for use in all eCommerce API call. This parameter refers to a database ID (dxcomp4.c4_id) and should only be used in instances where a customer has multiple company databases and wishes to make eCommerce calls that should hit a company database other than their default. There is no specific API call related to setting DatabaseIDs since the Database ID can be specified as an optional parameter in any and all API calls in the eCommerce offering. When provided in call, the call that is made will target the company database which matches the DatabaseID (c4_id) specified. This logic was introduced in Session.Current() and is checked before every API call.

For example, assume a customer has two company databases:

  • First Database
  • Name: DatabaseA
  • ID: 1
  • Default: true
  • Second Database
  • Name: DatabaseB
  • ID: 2
  • Default: false

eCommerce API calls can specify DatabaseID=2 in instances where they wish for the call to be made against DatabaseB. Any time a call is made without the DatabaseID parameter, the default database will always be pointed to, in this case "DatabaseA". This parameter is available to every eCommerce API function and should be specified in all calls intended to hit a database other than the default.

Setting via ini Value

Similarly to the approach covered in the "Setting via Header Value" sub-section above, a value can be specified in the Deacom.ini file in the eCommerce backend installation directory for which company database to run the eCommerce queries against. This approach alleviates the necessity to pass a header value with each call to the API and can be done by adding a property, ECOMMERCECOMPANYDATABASEID, with the ID dxcomp4 record that you wish to specify as the eCommerce company database.

Configuring a User and adding wishlist items

A user must first be created in (whether by adding it in Deacom or by usage of User.Register). Afterwards, the user may be logged into the site, their email address and password can be modified, a Ship-to and Broker may be assigned, and parts may be added to their standard order. The ability to add and remove wishlist items for a user may also be configured.

Logging a user into the site - /User/Login

Once a user has been created, this call will be used to log the user into the site. In this call, the password must be encrypted; it is plain text in the example below for demonstration purposes. Additionally, after this call is successful, a SessionID will be generated that ties to the appropriate User, Cart, Bill-to, and Ship-to. For more information, refer to the Overview section on this page.

Notes: 1. The /User/Login call will automatically set any current, active carts to the user so they may continue their session. This is in the event that a timeout occurs and the user wishes to resume shopping with the same cart they left off with. 2. If the "User Must Change Password At Next Login" (cu_chgpass) field is checked on the eCommerce User Record, this API will return the "This user must reset password" message. In this case, the User/ForgotPassword API will be called since that API call sets a new password for the user.

Parameters

  • Username - the username of the user attempting to login
  • Password - the associated password of the user attempting to login
  • FromFrontEnd (optional) - indicates whether the login is coming from a front-end UI. Users with "cu_statelessapionly" set to true are not allowed to log in if this parameter is true. Available beginning in version 16.07.055.

Example Call

http://localhost:8080/User/Login?Username=example&Password=Password1

Example Response - Success

The below is an example of a successful call response.

{

"LoginResult": {

"error": {},

"response": {

"User.Login": {

"Success": true,

"User ID": 10

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid password.

{

"LoginResult": {

"error": {},

"response": {

"User.Login": {

"Error": "The provided password is not correct."

}

}

}

}

Logging a user into the site - /User/LoginPost

As of version 16.04.096, the user can also use a POST request instead of the GET request above to login. This process simply requires language changes in User.Login to User.LoginPost, and carries a distinct advantage over the GET call - being less prone to exposing sensitive user data if the database is compromised by an attacker. The respective example responses above will remain the same, with the minor difference of having "Post" connected to User.Login. POST requests are also available for Cart/CheckoutPost. Optional parameter: FromFrontEnd - indicates whether the login is coming from a front-end UI. Users with "cu_statelessapionly" set to true are not allowed to log in if this parameter is true. Available beginning in version 16.07.055.

Registering a new user - /User/Register

Once a user has been created, this call will be used to register the new user. In this call, a SiteID header variable must be specified. As a result, new records will be created in dmcmsuseracc, dmbill, dmship (main app database) and dmuseracc (ecommerce database).

Parameters

  • LastName - the last name of the user
  • Email - the email address of the user
  • Password - the password of the user
  • Phone - the phone number of the user
  • Street - the billing street of the user
  • City - the billing city of the user
  • State - the billing state of the user
  • Zip - the billing zip of the user

Optional Parameters:

  • First Name - the first name of the user
  • Street2 - the billing second street line of the user
  • ShippingStreet - the shipping street of the user
  • ShippingStreet2 - the shipping second street line of the user
  • ShippingCity - the shipping city of the user
  • ShippingState - the shipping state of the user
  • ShippingZip - the shipping zip of the user
  • Approved - a boolean value indicating whether the user's login approval should be marked as true. This value will default to true if not otherwise specified, meaning new users will be approved by default.
  • Contact
  • Dear (Bill-To Record) - The name of the person in the Dear field (bi_dear) of the Bill-To record in DEACOM.
  • Dear (Ship-To Record) - The name of the person in the Dear field (sh_dear) of the Ship-To record in DEACOM.
  • ServiceType(optional) - the service type (sh_svctype) of the Ship-To Company. Options are "None", "Business", "Mixed", "Residential", "Unknown"
  • AddressValidated(optional) - date field - specifies the date (sh_addressvalid) the address was last validated.
  • GuestUser - used to set the "Guest User" (cu_guestuser) checkbox on the Edit eCommerce User form when new user accounts are created. Defaults to False. If set to True, the "Guest User" checkbox will be checked when guest users are created within the eCommerce application. Accounts marked as "Guest User" will not have access to the API function calls listed below.
  • IsB2BCustomer - This parameter controls a newly standardized UDF tied to the user account, called "u_is_b2b_customer". This UDF's data will be fetched and returned in a new node called "B2B" when running "User/GetData", if the "u_is_b2b_customer" UDF is set up in the system. Added to support situations where companies need a way to distinguish Bill-Tos as B2B or B2C. The setting on the customer will drive different functionality on the ecommerce site according to the wireframes.
  • OrganizationName - When this parameter is passed, it takes precedence over the "FirstName" and "LastName" parameters for the "bi_name" of the new Bill-To and the "sh_name" of the new Ship-To. It is also directly applied to "co_company" for the created Contact, if the eCommerce site creates Contacts for each new user.
  • CurrencyID - available beginning in version 17.01.053, this parameter that allows a currency to be assigned on the new object. See the eCommerce and Foreign Currency section at the top of the page for more details.

API Function Calls Restricted For Guest Users

Accounts marked as "Guest User" will not have access to the following API calls:

  • BillTo/GetCreditCards
  • BillTo/AddCreditCard
  • BillTo/UpdateCreditCard
  • Cart/AddStandardOrderToCart
  • User/Update
  • User/ChangePassword
  • User/AddToStandardOrder
  • User/GetOrderHistory
  • User/GetOrderHistoryDetail

Notes:

When registering for an account with this endpoint, the value in the "Minimum Order Extension" field on the Edit eCommerce User form will be set to the value in the "Minimum Order Extension" field on the Customer Defaults tab if no override was specified on the Edit eCommerce User form. Note that a value of zero counts as an override.

Version 16.04 allowed the User/Update call to update the security question selected for the user as well as the security answer but only if a password has been provided and its correct for that user.

Version 16.04 Added functionality to the User/Update call to handle if the frontend sends a ua_chgpass=true with the Useraccount object. In this case, we now set ua_chgpass=true for that user record. This was added for the frontend to be able to set the value on the user that dictates that the user must change his/her password at next login. This is useful because when we send out a temporary password, it's possible for the user to use this password indefinitely and that's not the desired functionality for some customers. Note: In eCommerce, password reset emails now expire after 30 minutes, and each password reset link is only usable once. This is accomplished by using an in-memory dictionary to store valid password reset authorization strings. These strings are only preserved for 30 minutes, and are deleted if used. Users will only be able to successfully reset their password if the authorization string from their password reset email is found in the dictionary.

Beginning in version 16.04.150, the "ua_newsletter" field is now available to the User/Update endpoint.

Updating a user - /User/Update

In version 16.07.077 the "User/Update" endpoint is now capable of saving values to the "ua_allowsaturday" and "ua_allowsunday" fields. This supports the ability to enforce password requirements when editing a password in Account Settings.

Example Call

http://localhost:8080/User/Register?FirstName=Mr E.&LastName=Commerce&[email protected]&Password=test&Phone=1231231234&Street=601 Lee Road&City=Chesterbrook&State=PA&Zip=19087&Street2=Test&ShippingStreet=123 Fake Street&ShippingStreet2=Unit A&ShippingCity=New York&ShippingState=NY&ShippingZip=10001

Example Call using the GuestUser parameter

http://localhost:8181/User/Register?FirstName=Guest&LastName=User&[email protected]&Password=123&Phone=1231231234&Street=601 Lee Road&City=Chesterbrook&State=PA&Zip=19087&GuestUser=true

The above call will create a new user named '[email protected]' which has limited API access due to its guest status. This user can now be logged in with the User/Login call, example: http://localhost:8181/User/[email protected]&Password=123

Example Response - Success

The below is an example of a successful call response.

{

"User.Register": {

"Success": true,

"User ID": 2038,

"User Login": "[email protected]"

}

}

Example Response - Failure

The below is an example of a failed call response. An error will be returned under the following conditions:

  • A user with the specified email address already exists.
  • A first name, last name, or email address was left blank.
  • A password was not provided.
  • A broker is specified but is not valid.
  • Some of the billing address was left blank (street, city, state, zip).
  • A shipping address was provided but left partially blank.
  • A SiteID header variable was not specified.
  • A username/user account already exists. (The User/Register API will check to see if the username/user account exists before the password check occurs.)

{

"User.Register": {

"Error": "A user with the specified email address already exists."

}

}

Changing a guest account to a verified account - /User/SetGuest

This function takes no parameters and will take the user currently linked to the session and change that user from a guest account to a "verified" account. Note that User/Login APIwill need to be called before User/SetGuest can be used.

Example Call

http://localhost:8181/User/SetGuest

Example Response - Success

The below is an example of a successful call response.

{

"SetGuestResult": {

"error": {},

"response": {

"User.SetGuest": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of the current user being a non-guest (authenticated) account.

Sample failure response:

{

"SetGuestResult": {

"error": {},

"response": {

"User.SetGuest": {

"Error": "This user account is already an authenticated account."

}

}

}

}

Modifying the email address of a user - /User/ChangeEmail

Once a user has been created, this call will be used to modify the user's email address. Note that this API call must have the SiteID variable specified in the header.

Parameters

  • Email - the email address of the user
  • UpdateLoging(optional) - a boolean value indicating if the user’s login email be updated as well.
  • UpdateBillTo(optional) - a boolean value. When true, the email address of the User's Bill-To will also be updated.

Example Call

http://localhost:8080/User/[email protected]

Example Response - Success

The below is an example of a successful call response.

{

"ChangeEmailResult": {

"error": {},

"response": {

"User.ChangeEmail": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid User ID.

{

"ChangeEmailResult": {

"error": {},

"response": {

"User.ChangeEmail": {

"Error": "Could not find a user with an ID of 18."

}

}

}

}

Modifying the password of a user - /User/ChangePassword

Once a user has been created, this call will be used to modify the user's password. In this call, the password must be encrypted; it is plain text in the example below for demonstration purposes. Note that this API call must have the SiteID variable specified in the header.

Parameters

  • NewPassword - the new password the user would like to set
  • OldPassword - the old password of the user
  • Login (optional) - Login name of the user. This parameter is used to specify which user to change the password for.

Example Call

http://localhost:8080/User/ChangePassword?NewPassword=Password2&OldPassword=Password1

Example Response - Success

The below is an example of a successful call response.

{

"ChangePasswordResult": {

"error": {},

"response": {

"User.ChangePassword": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of an incorrect password specified as the old password.

{

"ChangePasswordResult": {

"error": {},

"response": {

"User.ChangePassword": {

"Error": "The old password provided is not correct."

}

}

}

}

Resetting a user's password - /User/ForgotPassword

When this API is called, the system will update the eCommerce user's password to a random string of letters and numbers, and then return that string in the API as the new password. The /User/ChangePassword API can then be used to update the users password.

Required Parameters:

  • Username - username of the eCommerce User

Optional Parameters:

  • SendEmail - defaults to False. If set to True, send the user an email from the Trigger Email Address in System > Options to the Email Address set in dmcmsuseracc.cu_email for that user stating "Temporary Password: <<new password>>" the new password should come from the returned value of the User.ForgotPassword API. Note: Beginning in version 16.04, password reset emails now expire after 30 minutes, and each password reset link is only usable once.
  • SalesmanID - this parameter should be used in the front-end if the user requests a password reset while browsing on a custom Webstore subdomain. If this parameter is passed, a Salesman with the chosen ID will be fetched. If this Salesman exists and has a "u_webstore_link" UDF associated with it, then the subdomain stored in the UDF will be grabbed. This UDF's value will become the new domain name in the generated "ForgotPassword" email. This is useful for generating password reset links that keep the user on the same domain/subdomain that they were using to browse the website when they requested the password reset, instead of redirecting them to the default B2B portal. Available beginning in version 16.04.131.

Example Call

https://localhost:8181/User/[email protected]

Example Response - Success

{

"ForgotPasswordResult": {

"error": {},

"response": {

"User.ForgotPassword": {

"Success": true,

"New Password": "2b1a1e11"

}

}

}

}

Example Response - Failure

{

"ForgotPasswordResult": {

"error": {},

"response": {

"User.ForgotPassword": {

"Error": "An active user could not be found with a login of '[email protected]'."

}

}

}

}

Logging a user out of a site - /User/Logout

Parameters

  • None

Example Call

https://localhost:8080/User/Logout

Example Response - Success

{

"LogoutResult": {

"error": {},

"response": {

"User.Logout": {

"Success": "Log Out Successful"

}

}

}

}

Example Response - Failure

{

"LogoutResult": {

"error": {},

"response": {

"User.Logout": {

"Error": "User is not currently logged in."

}

}

}

}

Deactivate a User - /User/Deactivateuser

Required Paramaters

  • None

Optional Paramaters

  • UserID - ua_id/cu_id. If passed, deactivate this user. Otherwise get the logged-in user with UserAccount.GetUser(poSession) Returns: Success result (true, error) If the useraccount is already deactivated the system will prompt with this informaion

Example Call:

http://localhost:8181/User/DeactivateUser?SiteID=1&UserID=1

Example Response - Success

"DeactivateUserResult": {

"error": {},

"response": {

"User.DeactivateUser": {

"Success": true,

"Result": "Deactivation succeeded"

}

}

}

}

Example Response - Failure (Required Param Missing)

"DeactivateUserResult": {

"error": {},

"response": {

"User.DeactivateUser": {

"Error": "Argument Error - No UserID was specified, but no User Account is currently logged in. If a UserID is not specified, this endpoint requires an active User Account login."

}

}

}

}

Getting the Bill-to Companies of a user - /User/GetBillTo

This call is used to gather the Bill-to Company related to an eCommerce user. The call uses the UserID connected to the SessionID to find the Bill-to associated with it. The following fields will be returned: bi_id, bi_name, bi_street, bi_city, bi_state, bi_zip, bi_contact, bi_phone, bi_email

Note: If the "bi_credflag" flag on the Bill To record is set to true for the logged in customer, this API call will calculate the available credit for the customer and return this information in the "availcred" field in this API call. This information will be made available to the front end in order to determine if payment is needed or the order can be placed on credit.

Example Call:

http://localhost:8080/User/GetBillTo

Example Response - Success

{

"GetBillToResult": {

"error": {},

"response": {

"User.GetBillTo": {

"BillTo": {

"bi_id": 2115,

"bi_name": "CompanyName",

"bi_active": true,

"bi_street": "601 Lee Rd",

"bi_street2": "Floor B",

"bi_city": "Chesterbrook",

"bi_state": "PA",

"bi_zip": "19087",

"bi_phone": "123-123-1234",

"bi_fax": "",

"bi_contact": "User Name",

"bi_country": "US",

"bi_phext": "",

"bi_email": "[email protected]",

"bi_poreqd": false,

"bi_credhld": null,

"bi_credflag": false,

"bi_reqcpart": false,

"bi_grid": 1

}

}

}

}

}

Example Response - Failure

{

"GetBillToResult": {

"error": {},

"response": {

"User.GetBillTo": {

"Error": "Could not find a user account associated with this session."

}

}

Getting the Ship-to Companies of a user - /User/GetShipTo

This call is used to gather all Ship-to Companies related to an eCommerce user. The call uses the SessionID to find the Bill-to associated with it, then return any Ship-to Company name and address fields linked to the Bill-to. The following fields will be returned: sh_name, sh_street, sh_street2, sh_city, sh_state, sh_zip, sh_country, sh_email, sh_phone.

Parameters

  • ShipToID (optional) - the ID of the single Ship-To linked to the User.

Example Call

http://localhost:8080/User/GetShipTo

Example Response - Success

{

"GetShipToResult": {

"error": {},

"response": {

"User.GetShipTo": {

"ShipTos": [

{

"sh_id": 2671,

"sh_name": "Test Test",

"sh_street": "",

"sh_street2": "",

"sh_active": true,

"sh_trid": 12,

"sh_city": "",

"sh_state": "",

"sh_zip": "",

"sh_phone": "",

"sh_fax": "",

"sh_credhld": null,

"sh_credflag": false,

"sh_contact": "eCommerce",

"sh_country": "US",

"sh_phext": "",

"sh_email": "[email protected]",

"sh_reqcpart": false,

"sh_waid": 0,

"sh_brid": 0

"sh_dear": "Mr. Smith, Tom"

}

]

}

}

}

}

Example Response - Failure

{

"GetShipToResult": {

"error": {},

"response": {

"User.GetShipTo": {

"Error": "Could not find a user account associated with this session."

}

}

}

}

Modifying the Bill-to Company of a user - /User/ChangeBillTo

Once a user has been created, this call updates a user's Bill-to ID record. The Ship-to ID can also be updated by this function, but if no Ship-to ID is provided then that user's linked Ship-to will be cleared. Note that this API call must have the SiteID variable specified in the header.

Parameters

  • BillToID - The Bill-to ID to set on the user
  • ShipToID (optional) - The Ship-to ID to set on the user

Example Call

http://localhost:8080/User/ChangeBillTo?BillToID=2129&ShipToID=2682

Example Response - Success

{

"ChangeBillToResult": {

"error": {},

"response": {

"User.ChangeBillTo": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response. An error will be returned if either the BillToID or ShipToID is invalid.

{

"ChangeBillToResult": {

"error": {},

"response": {

"User.ChangeBillTo": {

"Error": "Could not find a ship-to customer with an ID of 123."

}

}

}

}

Modifying the Ship-to Company of a user - /User/ChangeShipTo

This call is used to check for a dmbillship link between the ShipToID provided and the Bill-to ID on the user. If none exists, one will be created. Note that this API call must have the SiteID variable specified in the header.

Parameters

  • ShipTo - the Ship To Company ID from DEACOM.

Example Call

http://localhost:8080/User/ChangeShipTo?ShipToID=Y

Example Response - Success

The below is an example of a successful call response.

{

"ChangeShipToResult": {

"error": {},

"response": {

"User.ChangeShipTo": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid Ship-to ID.

{

"ChangeShipToResult": {

"error": {},

"response": {

"User.ChangeShipTo": {

"Error": "Could not find a Ship - to customer with an ID of 158."

}

}

}

}

Modifying the Broker of a user - /User/ChangeBroker

Once a user has been created, this will be used to modify the user's Broker. Note that this API call must have the SiteID variable specified in the header.

Parameters

BrokerID - the Broker ID from DEACOM

Example Call

http://localhost:8080/User/ChangeBroker?BrokerID=Y

Example Response - Success

The below is an example of a successful call response.

{

"ChangeBrokerResult": {

"error": {},

"response": {

"User.ChangeBroker": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid Broker ID.

{

"ChangeBrokerResult": {

"error": {},

"response": {

"User.ChangeBroker": {

"Error": "Could not find a Broker with an ID of 34."

}

}

}

}

Adding parts to a user's standard order - /User/AddToStandardOrder

Once a user has been created, this call will be used to add parts to their standard order.

This call will enforce the "Bill-To/Ship-To Cross Ref Required For Sales" flag on the DEACOM item master record. If a user selects an item with this flag checked, the system will verify that a customer part cross reference exists for the customer logged into the eCommerce site and the selected item. If a match is not found an error will be returned and the call will not be applied. Companies may need to code their front end to display the appropriate message in this situation.

Parameters

  • PartID - the Part ID from DEACOM
  • Quantity - the number of units of the part being added

Example Call

http://localhost:8080/User/AddToStandardOrder?PartID=YYYY&Quantity=Z

Example Response - Success

The below is an example of a successful call response.

{

"AddToStandardOrderResult": {

"error": {},

"response": {

"User.AddToStandardOrder": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of specifying a Part ID that is not flagged as "Active" in DEACOM.

{

"AddToStandardOrderResult": {

"error": {},

"response": {

"User.AddToStandardOrder": {

"Error": "Part u0027SP - 200400057200 - 001 u0027 is not active and cannot be added to the Standard Order."

}

}

}

}

Obtaining user information - /User/GetData

This function call returns all relevant user data for the UserID passed into this API from the User.Login call.

The following fields are returned:

  • All dmcmsuseracc fields (except for cu_password, cu_cqid, and cu_sqanswer -- for security purposes)
  • All dmcmsuseracc user fields
  • bi_name from linked Bill-to, if any
  • sh_name from linked Ship-to, if any
  • br_name from linked Broker, if any
  • security question and answer - Version 16.04 offers the ability to add a security question chosen for the eCommerce user and its answer to be returned by user.GetData() as well as all available security questions on dmsecquest.

Notes:

The "bi_credflag" value is reported for the current user's Bill-To when running the "User/GetData" endpoint.

Beginning in version 16.04.125, the terms id (te_id) for the Term attached in the current user's attached Bill-To record will be returned with this endpoint to support the new Terms/GetData endpoint.

Example Call

http://localhost:8080/User/GetData

Example success response

{

"GetDataResult": {

"error": {},

"response": {

"User.Login": {

"Success": true,

"cu_active": true,

"cu_allowsaturday": true,

"cu_allowsunday": true,

"cu_biid": 977,

"cu_brid": 0,

"cu_ccid": 1,

"cu_csid": 3,

"cu_email": "mwelsh @deacom.com",

"cu_id": 10,

"cu_login": "mwelsh",

"cu_loginapproved": true,

"cu_minord": 0.0000000,

"cu_minordtype": "Dollars",

"cu_newsletter": true,

"cu_orderconfirm": false,

"cu_paymentrequired": true,

"cu_phone": "",

"cu_samedaycharge": 0.0000000,

"cu_shid": 0,

"cu_specialoffer": false,

"bi_name": "4 STATE SUPPLY",

"sh_name": null,

"br_name": null,

"u_ecom_char_test": "sample value",

"u_ecom_date_test": "03 / 01 / 2019",

"u_ecom_bool_test": "Yes",

"u_ecom_memo_test": "sample memo",

"u_ecom_numeric_test": "10.00",

"u_ecom_picklist_test": ""

}

}

}

}

Example failure response

{

"GetDataResult": {

"error": {},

"response": {

"User.GetData": {

"Error": "A user could not be found with an ID of 1000000."

}

}

}

}

Obtaining an User's Orders - /User/GetOrder

Once a user has placed one or more orders, this call will be used to obtain order information (order number, ID, date, notes [or_notes], and dollar total) for every order currently in the cart for the SessionID.

Optional Parameters

  • ShipToID - the id (to_shid) for the Ship To Customer on the order. This will filter the orders so that the only content in the return will be orders with a matching Ship-To ID (to_shid) to what is specified. No content is visually changed in the returned JSON versus before this edit was made, except filtration on the results. This parameter will ONLY be used successfully if the user is logged in on the eCommerce site with an account whose CMS User Ship-To OR linked Bill-To Assignments contain the passed Ship-To ID. If the user is not authorized to view the data due to not having a matching Ship-To ID on either of these properties, a new error will be thrown: "Argument Error - The specified Ship-To ID parameter does not match the current CMS User or any of its Bill-To Assignments."
  • OrderType - the DEACOM sales order type. When an argument is supplied for this, the sytsem will apply this filter along with the others to the user orders returned. (note the exact character 't' will be passed in this case) - This paramater supports the ability for filtering an order's result by order type.
  • InclusionFilter - used to filter for orders with a to_paydate of 'NULL'. See example call below for details. This parameter supports the ability to generate customer statements via the User/GetStatement call. Added in version 16.04.122.
  • ExclusionFilter - used to filter out orders with a to_paydate of 'NULL'.
  • CheckDueDate - If this parameter is passed as TRUE, order invoice/due dates will be returned. Added in version 16.04.125. In addition to this parameter, a new set of nodes have been added to this endpoint which report information about the Terms linked to the Bill-To on the order. When fetching orders, there will always be a "Terms" node with a "TermID" sub-node. If the "CheckDueDate" parameter is passed as TRUE, other nodes will exist depending on the state of the data as indicated below:
    • If the order has been invoiced and a due date could be calculated, the sub-nodes "InvoiceDate" and "DueDate" will be present, with the calculated dates.
    • If the order has not been invoiced yet, the "DueDate" node will be absent. The "InvoiceDate" node will be present, which will say "Not yet invoiced".
    • If the order has been invoiced, but a due date could not be calculated due to a data setup problem, the "DueDate" and "InvoiceDate" node will both be present, but will say "error" for the dates that could not be calculated.

Notes -

  • If the "Description" parameter is used in the Cart/Checkout/ call then the /User/GetOrder call will Ensure that to_descrip is represented in the response
  • Beginning in version 16.04.125, the terms id (te_id) for the Term attached in the current user's attached Bill-To record will be returned with this endpoint to support the new Terms/GetData endpoint.
  • Version 16.04.127 introduces a change which now enables the /User/GetOrder endpoint to display due date information about the orders that are being returned. This new information is available within the "Terms" node in the returned JSON.
  • Beginning in version 16.05.130 this API response now contains an "OrderConfirmation" node. This node contains the obfuscated order number that is supplied upon checkout.
  • Version 16.04.127 adds the "ShipToName" value to the ShipToInfo mode. This value reports the full name of the Ship-To that is attached to the Sales Order line. (This will only report a value when a Ship-To is specified on the line, which occurs with Master Orders.)
  • The to_condate (confirmation date) field is now available and will be returned in the call for this API beginning in version 17.01.030.

Example Call

http://localhost:8181/User/GetOrder?PageNumber=1&NumberOfItemsPerPage=25&SortByPO=false&SortByOrderDate=false&OrderByAsc=false&SiteID=1&ShipToID=3672

Obtaining a User's Order History - /User/GetOrderHistory

Once a user has placed one or more orders, this call will be used to obtain order information (order number, ID, date, and dollar total) for every order linked to the SessionID. Note that shipping status is included in the results but not inputted. The results will show a shipping status of shipped, not shipped, or partially shipped.

Optional Parameters

  • StartDate -- The start date to filter on. No Sales Orders with order dates before the StartDate will be returned.
  • EndDate -- The end date to filter on. No Sales Orders with order dates after the EndDate will be returned.
  • BillPO -- The Purchase Order number supplied by the Bill-to Company.
  • SortByPO -- Determines if the returned list of orders is sorted by to_billpo. If SortByPO is true, the system will sort by to_billpo rather than order number, which is the default behavior.
  • OrderByAsc - Determines if the returned list of orders will be ordered in ascending order. If OrderByAsc is true, the system will returns the list of orders in ascending order rather than in descending order, which is the default behavior.
  • The StartDate and EndDate parameters should function the same way that the Start and End dates parameters work on prefilters within main app (ex: Sales Order Management) In all cases, only orders meeting the date filter criteria were returned. Note: if no orders meet the criteria, a response saying no orders were found will be returned (as with all filters for this function).

Example Calls

http://localhost:8181/User/GetOrderHistory

http://localhost:8181/User/GetOrderHistory?StartDate=09012020&EndDate=09012020

http://localhost:8181/User/GetOrder?SiteID=2&PageNumber=1&NumberOfItemsPerPage=25&SortByPO=false&SortByOrderDate=false&OrderByAsc=false&InclusionFilter=[{'to_paydate':'NULL'}] - (this call will only return unpaid orders)

Example Response - Success

The below is an example of a successful call response.

{

"GetOrderHistoryResult": {

"error": {},

"response": {

"User.GetOrderHistory": {

"Orders": [

{

"OrderNumber": "2019-14668-00",

"OrderID": 7484,

"OrderDate": "09/25/2019",

"OrderSubTotal": "$90.00",

"OrderTotal": "$90.00",

"PaymentType": "",

"ShippingStatus": "Not shipped"

},

{

"OrderNumber": "2019-14667-00",

"OrderID": 7483,

"OrderDate": "09/25/2019",

"OrderSubTotal": "$90.00",

"OrderTotal": "$90.00",

"PaymentType": "Visa",

"ShippingStatus": "Not shipped"

},

{

"OrderNumber": "2019-14098-00",

"OrderID": 6672,

"OrderDate": "06/19/2019",

"OrderSubTotal": "$90.00",

"OrderTotal": "$95.40",

"PaymentType": "",

"ShippingStatus": "Not shipped"

}

]

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of not providing a Bill-to ID nor a User ID, or no orders existing for the specified parameters.

{

"GetOrderHistoryResult": {

"error": {},

"response": {

"User.GetOrderHistory": {

"Error": "Could not find any orders for the given User or Bill-to ID."

}

}

}

}

Obtaining a User's Order Detail - /User/GetOrderHistoryDetail

This call returns the same information as the Sales Order Detail report in DEACOM.

Required Parameters

  • SessionID - users session ID

Optional Parameters

  • Fields - array of field names, can contain ship-to, bill-to, order line fields and user fields, order header fields and user fields. If empty, return the default set of fields that is returned when running the order detail report.
  • PartID - PartID to filter results
  • StartDate - corresponding to to_orddate as a start date filter
  • EndDate - corresponding to to_orddate as an end date filter
  • Order Number - Allows filtering based on a single order. Note that utilizing the OrderNumber parameter functions the same way as main app in that if a specific order is provided, all other optional parameters will be ignored.
  • DistinctPartsOnly - Boolean. Defaults to false. If set to true, the call will only display a distinct list of all part numbers ordered. Additional parameters can be specified to further filter the distinct list of part numbers ordered. An example with a time frame specified is included in the Example Call section below. This example

This API should return all fields available to a sales order detail report, essentially running the same code and using the above parameters to filter the data. The User in the session should be used to get the Bill-To ID assigned to the User and initially only filter off of that. Then use the optional parameters if any are filled in.

Example Call

http://localhost:8181/User/GetOrderHistoryDetail

http://localhost:8181/User/GetOrderHistoryDetail?DistinctpartsOnly=TRUE&StartDate=04/15/2020

Example Response - Success

{

"GetOrderHistroyDetailResult": {

"error": {},

"response": {

"User.GetOrderHistoryDetail": {

"Orders": [{

"bi_name": "4 STATE SUPPLY",

"or_exten": 60,

"or_ordquant": 2,

"or_price": 30,

"or_prid": 3700,

"or_shipquant": 0,

"pr_codenum": "Finish Good 01",

"sh_name": "4 STATE SUPPLY",

"to_orddate": "07/03/2019",

"to_ordnum": 20191431700,

"to_ordtype": "s",

"to_shipped": " / / ",

"tr_name1": "FedEx"

}]

}

}

}

}

Example Response - Failure

{

"GetOrderHistoryDetailResult": {

"error": {},

"response": {

"User.GetOrderHistoryDetail": {

"Error": "Could not find any orders for the given User and the specified parameters."

}

}

}

}

Obtaining previously ordered items - /User/GetOrderedParts

When called, this API returns all historically-ordered eCommerce parts with the same Bill-To company as that of the logged in user. The call filters out duplicates by only taking the unique part id number (pr_id). Pagination is supported by using the appropriate parameters listed below.

The following fields are returned as a result of this call:

  • pr_codenum - user-defined product name
  • pr_id - unique identifier from the DEACOM part number (dmprod) table
  • pr_descrip - user-defined product description
  • pr_lispric - product list price
  • pr_picture - product image from the DEACOM picture (dmpict) table WHERE pi_dcid = selected document category AND pi_recid = pr_id

Note: Beginning in 16.04.130, this call returns a "TotalNumberofParentProducts" node in the returned JSON. This will be used to display the correct number of top-level eCommerce products on specific search pages, specifically, the number of items with unique "cp_epid" values.

Required Parameters:

  • N/A

Optional Parameters:

  • PageNumber - the page number for pagination - default 1
  • NumberOfItemsPerPage - number of items to display per page - default 5
  • ReturnAllItems - override for pagination - default false
  • PartNumber - Filter by part number (pr_id) - default ""/NA
  • PartName - Filter by part name (pr_codenum) - default ""/NA

Example Call

http://localhost:8181/User/GetOrderedParts

Example Response - Success

{

"GetOrderedPartsResult": {

"error": {},

"response": {

"User.GetOrderedParts": {

"OrderedParts": [

{

"pr_codenum": "Bald Eagle",

"pr_id": 7853,

"pr_descrip": "North american bird of prey",

"pr_lispric": 100.0,

"pr_picture": "2122"

},

{

"pr_codenum": "Beagle",

"pr_id": 7847,

"pr_descrip": "Small scent hound",

"pr_lispric": 250.0,

"pr_picture": "2112"

},

{

"pr_codenum": "Blue Betta Fish",

"pr_id": 7834,

"pr_descrip": "Aenean iaculis tellus porta, mo",

"pr_lispric": 20.0,

"pr_picture": "2128"

},

{

"pr_codenum": "Polar Bear",

"pr_id": 7848,

"pr_descrip": "A hypercarnivorous bear",

"pr_lispric": 500.0,

"pr_picture": "2105"

}

]

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of no items having been ordered before for a particular user.

{

"GetOrderedPartsResult": {

"error": {},

"response": {

"User.GetOrderedParts": {

"OrderedParts": []

}

}

}

}

Adding items to a wishlist - /User/AddToWishlist

When called, this API will append the item to the data already in ua_wishlist/cu_wishlist and continue to build the array of items.

Parameters

  • UserID - linked to dxcmsuseracc.cu_id
  • PartID - linked to dmprod.pr_id

Example Call

http://localhost:8181/User/AddToWishlist?SiteID=3&UserID=2043&PartID=7839

Example Response - Success

{

"AddToWishlistResult":{

"error":{},"response":{

"User.AddToWishlist":{

"Success":true,"Result":"9777"

}

}

}

}

Example Response - Failure

{

"AddToWishlistResult":{

"error":{},"response":{

"User.AddToWishlist":{

"Error":"Argument Error - The specified product is already stored in this User's Wishlist."

}

}

}

}

Remove items for a wishlist - /User/RemoveFromWishlist

When called, this API will remove the specified item from the array already in ua_wishlist/cu_wishlist.

Parameters

  • UserID - linked to dxcmsuseracc.cu_id
  • PartID - linked to dmprod.pr_id

Example Call

http://localhost:8181/User/RemoveFromWishlist?SiteID=3&UserID=2043&PartID=7838

Example Response - Success

{

"RemoveFromWishlistResult":{

"error":{},"response":{

"User.RemoveFromWishlist":{

"Success":true,"Result":"9777"

}

}

}

}

Example Response - Failure

{

"RemoveFromWishlistResult":{

"error":{},"response":{

"User.RemoveFromWishlist":{

"Error":"Argument Error - This User's Wishlist is already empty."

}

}

}

}

Obtain a users wishlist - /User/GetWishlist

When called, this API will return a JSON object with the pr_codenum, pr_descrip, product image, and price of each part ID stored in the wishlist field created above.

Paramaters

  • UserID - linked to dxcmsuseracc.cu_id

Example Call

http://localhost:8181/User/GetWishlist?SiteID=3&UserID=2043

Example Response - Success

{

"GetWishlistResult":{

"error":{},"response":{

"User.GetWishlist":{

"Success":true,"Result":{

"Item_1":{

"Name":"Multi-Seed Roasted Garlic",

"Description":"crackers with a savory taste and satisfying crunch. Made with sesame,quinoa,flax and amaranth seeds with a savory, roasted garlic

taste.",

"PartID":9777,

"Price":3.5,

"CategoryName":"TBD",

"SubcategoryName":"",

"Active":true,

"HasOnHandQty":true,

"ImageIDs":"7953,7954,7955,7956"

},

"Item_2":{

"Name":"Protein Brownie Thins",

"Description":"Delicious, guilt-free dark chocolate brownie thins, baked to perfection with a satisfying

crunch.",

"PartID":9771,

"Price":7.25,

"CategoryName":"TBD",

"SubcategoryName":"",

"Active":true,

"HasOnHandQty":true,

"ImageIDs":"5614,8748"

}

}

}

}

}

}

Example Response - Failure

{

"GetWishlistResult":{

"error":{},"response":{

"User.GetWishlist":{

"Error":"Argument Error - The [UserID] OR [Key] parameter is required, but neither was passed."

}

}

}

}

Obtain modified user records - /User/GetModifiedRecords

This API endpoint will obtain any modifications for user records in the specified time period. (Added in version 16.07.054)

Parameters

  • Site-ID (required) - the ID of the eCommerce site.

Example Call

http://localhost:8181/User/GetModifiedRecords?SiteID=1&StartDate=6/7/2022 00:01:00&EndDate=6/8/2022 19:00:00

Example Response - Success

The success response will be similar to the /General/GetModifiedRecords, but will only include information from the user table.

Example Response - Failure

N/A - Users may receive some generic errors in the case of a failure.

Obtain new user records - /User/GetNewRecords

This API endpoint will obtain information on any new user records in the specified time period. (Added in version 16.07.054)

Parameters

  • Site-ID (required) - the ID of the eCommerce site.

Example Call

http://localhost:8181/User/GetNewRecords?SiteID=1&StartDate=4/7/2022 00:01:00&EndDate=6/13/2022 13:00:00

Example Response - Success

The success response will be similar to the /General/GetNewRecords, but will only include information from the user table.

Example Response - Failure

N/A - Users may receive some generic errors in the case of a failure.

Obtain customer statements - /User/GetStatement

This API endpoint works in conjunction with the /User/GetOrder endpoint and is used generate customer statements for users based on the invoiced or paid status/date of the orders. Beginning in version 16.05.130, this endpoint is able to properly generate a confirmation PDF in systems that utilize multiple company databases.

Notes:

  • In version 16.05.130, this API now accepts an obfuscated order number or a plaintext order number when fetching the chosen document.
  • Beginning in version 16.04.128, this endpoint can now retrieve a PDF even if the user does not own the order, as long as the specified OrderNumber is an encrypted value.This allows authorized users, such as webstore administrators, to view orders placed on their webstore site. Since the encrypted order number is only disclosed at specific times to authorized users, this is a secure way to lock down access to order PDFs.

This API works similarly to the "User/GetOrder" endpoint when handling guest users. Guest users are now required to submit an encrypted order number in the "OrderNumber" parameter, along with the email address belonging to the Bill-To on the order in the new "EmailAddress" parameter. Supplying both of these parameters will produce the appropriate order confirmation documents as expected.

Required Parameters

  • Site-ID (required) - the ID of the eCommerce site.

Example Call

http://localhost:8181/User/GetStatement?SiteID=2&OrderNumber=20227431500&StatementType=Invoice

Example Call - Success

{

"GetStatementResult": {

"error": {},

"response": {

"User.GetStatement": {

"Count": 1,

"Documents": [

{

"Name": "Invoice.pdf",

"Description": "Invoice",

"Picture": ..............

}

}

}

}

}

}

Example Call - Failure

N/A - Users may receive a message indicating that no document(s) could be located.

Creating a Contact - /Contact/Create

When the user has "Create Contact Upon Registration" checked in the Edit eCommerce Site form, this API creates a contact. Must be linked to the dmcontpeople record.

Parameters

  • CompanyName - char
  • ContactPerson - requires at least one contact person to save.
  • LastName - stored in dmcontpeople.cp_lname

Optional Parameters

  • All dmcont fields

Updating a Contact -/Contact/Update

Update an existing contact in eCommerce.

Parameters

  • ContactID - int

Optional Parameters

  • All dmcont fields

Creating a Contact Person - ContactPerson/Create

When the user has "Create Contact Upon Registration" checked in the Edit eCommerce Site form, this API creates a contact person. Must be linked to the dmcont record.

Parameters

  • ContactID - int - dmcont.co_id
  • LastName - char - stored in dmcontpeople.cp_lname

Optional Parameters

  • All dmcontpeople fields

Updating a Contact Person - ContactPerson/Update

Update an existing contact person in eCommerce.

Parameters

  • ContactPersonID - int - dmcontpeople.cp_id

Optional Parameters

  • All dmcontpeople fields

Obtain Terms Information - Terms/GetData

This call, added in version 16.04.125, is used to return Terms information when a parameter identifying the Term has been passed in. To support this, the User/GetData and User/GetOrder endpoints have term id nodes which now also return the Terms (te_id) attached to the current user's attached Bill-To record.

Parameters (required)

  • SiteID - the ID of the eCommerce site
  • TermID - the ID of the Term on the user's Bill-To record.

Example Call

http://localhost:8181/Terms/GetData?SiteID=1&TermID=5

Example Response - Success

{

"GetDataResult": {

"error": {},

"response": {

"Terms.GetData": {

"Success": true,

"te_id": 5,

"te_name": Cash,

"te_billtype": Invoice,

"te_ccprocess": None,

"te_ccperc": 0.00,

"te_active": 1,

"te_discday": 0,

"te_disdayyear": "",

"te_discmon": 0,

"te_discoun": 0.0000,

"te_disctype": Number Of Days,

"te_dueday": 0,

"te_duedayyear": "",

"te_duemon": 0,

"te_duetype": Number Of Days,

"te_prepay": 0,

 

}

}

}

}

Example Response - Failure

An failure response would indicate that that the Terms ID specified could not be found.

Sales Records

Creating a Bill-to record - /BillTo/Create

When called, this API will create a new Bill-To for the passed in criteria, and link the new Bill-to to the Ship-To or User, when provided. A success message and the Bill-To ID will be returned upon a successful call.

Parameters

  • Name - the Bill-To name
  • Street (optional) - the Bill-To street
  • Street2 (optional) - the Bill-To street (cont'd)
  • Street3 (optional) - the Bill-To street (cont'd)
  • City (optional) - the Bill-To city
  • State (optional) - the Bill-To state
  • Zip (optional) - the Bill-To zip code
  • Phone (optional) - the Bill-To phone
  • Country (optional) - the Bill-To country
  • ShipToID (optional) - the Ship-To ID to link to
  • UserID (optional) - the User ID to link to
  • DBA (optional) - the entry in the DBA (Doing Business As) field
  • Contact (optional) - the Contact listed on the Bill-to record
  • Dear (optional) - The name of the person in the Dear field (bi_dear) of the Bill-To record in DEACOM.
  • CurrencyID - available beginning in version 17.01.053, this parameter that allows a currency to be assigned on the new object. See the eCommerce and Foreign Currency section at the top of the page for more details.

Note: The following fields are copied from the Bill To Company specified on the Customer Defaults tab via Tools > Maintenance > eCommerce Sites. when using the BillTo/Create API call: dmbill.bi_c3id, dmbill.bi_pastday, dmbill.bi_exday, dmbill.bi_creddueshipdays, dmbill.bi_credlim, dmbill.bi_exceed, dmbill.bi_credflag

Example Call

http://localhost:8181/BillTo/Create?Name=Ecom Test&Street=Test Street1&Street2=Test Street2&Street3=Test Street3&City=Test City&State=Test State&Zip=Test Zip&Phone=1234567890&[email protected]&Country=United States&UserID=10

Example Response - Success

{

"BillTo.Create": {

"Success": true,

"bi_id": 2226

}

}

Example Response - Failure

{

"BillTo.Create": {

"Error": "You must provide a Bill-To name."

}

}

Modifying a Bill-to record - /BillTo/Update

This function call updates a Bill-to record based on the new values passed in. The Bill-to record to be updated is determined by the default Bill-to on the current session's user, or the current session's cart if no user is logged in. The following fields can currently be set by this function: bi_name, bi_street, bi_street2, bi_city, bi_state, bi_zip, bi_phone, bi_fax, bi_email, bi_contact, bi_country, bi_phext, bi_active, bi_poreqd, bi_credflg, bi_reqcpart, bi_credhld, bi_grid, bi_said, bi_dba, and all dmbill user fields

Parameters

  • New Values - A string containing the lookup of fields and new values to set. Example: [{"bi_name":"eCommerce Test - Name"}, {"bi_street":"601 Lee Rd"},{"bi_active":"true"}, {"bi_credhld":"02/20/2019"}, {"bi_dba":"dba test"}]
  • UserFieldValues(optional) - A string containing the lookup of user field IDs (d1_id) and values to set. Example: [{"54":"eCommerce Test"}, {"73":"True"},{"242":"Test2"}]
  • UpdateEcommUser(optional) - A boolean value. When true, the email address or phone number of the current user will also be updated, in addition to updating these fields on the Bill-To.
  • Dear (optional) - The name of the person in the Dear field (bi_dear) of the Bill-To record in DEACOM.
  • RecordID(optional) - The RecordID parameter must match the cart's Bill-To or the user's Bill-To.

Example Call

http://localhost:8080/BillTo/Update?NewValues=[{"bi_name":"eCommerce Test - Name"}, {"bi_street":"601 Lee Rd"},{"bi_active":"true"}, {"bi_credhld":"02/20/2019"}, {"bi_dba":"dba test"}]&UserFieldValues=[{"54":"eCommerce Test"}, {"73":"True"},{"242":"Test2"}]

Example Response - Success

{

"UpdateResult": {

"error": {},

"response": {

"BillTo.Update": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response. An error will be returned under the following conditions:

A Bill-to could not be found for the given user/cart.

The NewValues parameter specifies a field that cannot be updated by this function.

A user field ID could not be identified.

{

"UpdateResult": {

"error": {},

"response": {

"BillTo.Update": {

"Error": "Could not find a Bill-To customer with an ID of 1000."

}

}

}

}

Obtaining Bill-to information - /BillTo/GetData

This function has no parameters. It will identify the Bill-To ID linked to the currently logged in user (or linked to the cart if no user is logged in) and will return all dmbill fields and dmbill user fields for that Bill-To.

Parameters:

  • CartBillToID - Optional. The id of the cart for the selected Bill-to

Example Call

http://localhost:8181/BillTo/GetData

Example Response - Success

"GetDataResult": {

"error": {},

"response": {

"BillTo.GetData": {

"Success": true,

"bi_active": true,

"bi_city": "Chesterbrook",

"bi_contact": "eCommerce",

"bi_country": "United States",

"bi_credflag": false,

"bi_credhld": "2019-02-20T00:00:00",

"bi_email": "[email protected]",

"bi_fax": "",

"bi_grid": 1,

"bi_id": 2136,

"bi_name": "eCommerce Test - Matt",

"bi_phext": "",

"bi_phone": "1231231234",

"bi_poreqd": false,

"bi_reqcpart": false,

"bi_state": "PA",

"bi_street": "601 Lee Rd",

"bi_street2": "Test",

"bi_zip": "19087",

"u_43": "",

"u_DUNS_Number": "True",

"u_use_order_splitter": "",

"u_ryan2": "Test2",

"u_ktest": "",

"u_newtest": "",

"u_BLAHBLAH": "",

"u_a": null,

"u_Test123456": "",

"u_Matt_Test": "",

"u_test73020132": "",

"u_test73020133": "",

"u_MattTest2": null,

"u_dee": "",

"u_test": null,

"u_Test1234567": "",

"u_RFC": "",

"u_Payment_Type": null,

"u_testssss": ""

}

}

}

Example Response - Failure

{

"GetDataResult": {

"error": {},

"response": {

"BillTo.GetData": {

"Error": "Could not find a bill-to customer with an ID of 21360."

}

}

}

}

Obtain modified Bill-To records - /BillTo/GetModifiedRecords

This API call will obtain information on modified records from the Bill-To (dmbill) table for the specified time period. (Added in version 16.07.054)

Parameters

  • Site ID (required) - the ID of the eCommerce site.

Example Call

http://localhost:8181/BillTo/GetModifiedRecords?SiteID=1&StartDate=6/7/2022 23:59:59&EndDate=6/9/2022 17:00:00

Example Response - Success

The success response will be similar to the /General/GetModifiedRecords, but will only include information from the Bill-To (dmbill) table.

Example Response - Failure

N/A - Users may receive some generic errors in the case of a failure.

Obtain information for new Bill-To records - /BillTo/GetNewRecords

This API call will obtain information on new records added to the Bill-To (dmbill) table for the specified time period. (Added in version 16.07.054)

Parameters

  • Site ID (required) - the ID of the eCommerce site.

Example Call

http://localhost:8181/BillTo/GetNewRecords?SiteID=1&StartDate=1/7/2022 23:59:59&EndDate=6/9/2022 17:00:00

Example Response - Success

The success response will be similar to the /General/GetNewRecords, but will only include information from the Bill-To (dmbill) table.

Example Response - Failure

N/A - Users may receive some generic errors in the case of a failure.

Creating a Ship-to record - /ShipTo/Create

This call is used to create a new Ship-to record with the parameters specified and link it to the Bill-to (if specified). Beginning in version 16.07.116, this API call has been converted from a GET request to a POST request.

Parameters

If either of the below parameters are provided, a link will be created between the Ship-to that gets created and the Bill-to customer specified (dmbillship).

  • Name - the name of the Ship-to Company
  • Street, Street2, Street3, CIty, State, Zip (optional) - the shipping address information for the Ship-to Company.
  • Phone, Email (optional) - the contact information for the Ship-to Company
  • BillToID (optional) - the Bill-to ID to link to.
  • UserID (optional) - the User ID to get the Bill-to ID from.
  • Country (optional) - the country of the Ship-to address.
  • DBA (optional) - the entry in the DBA (Doing Business As) field
  • Contact (optional) - the Contact listed on the Ship-to record
  • Dear (optional) - the name of the person in the Dear field (sh_dear) of the Ship-To record in DEACOM.
  • ServiceType(optional) - the service type (sh_svctype) of the Ship-To Company. Options are "None", "Business", "Mixed", "Residential", "Unknown"
  • AddressValidated(optional) - date field - specifies the date (sh_addressvalid) the address was last validated.
  • PhoneExt (optional) - Ship-To phone extension. This parameter saves the passed value to sh_phext when creating a Ship-To.
  • CopySalesSearchFromDefault - When this parameter is passed as true, the dmship.sh_s1id - dmship.sh_s5id fields will be copied from the current user's default Ship-To.
  • Fax(optional) - the fax number from the Ship-To company in Deacom. Corresponds to the "sh_fax" database field when saving the resulting Ship-To entry.
  • CurrencyID - available beginning in version 17.01.053, this parameter that allows a currency to be assigned on the new object. See the eCommerce and Foreign Currency section at the top of the page for more details.

Example Call

Sample call using UserID - http://localhost:8181/ShipTo/Create?Name=Ecom Test 2&UserID=X

Sample call using BillToID - http://localhost:8181/ShipTo/Create?Name=Ecom Test 3&BillToID=Y

Sample call using Country - http://localhost:8181/ShipTo/Create?Name=Ecom Test 2&Street=601 Lee Road&City=Chesterbrook&State=PA&Zip=19087&Country=US

Example Response - Success

{

"CreateResult": {

"error": {},

"response": {

"ShipTo.Create": {

"Success": true,

"sh_id": 2723

}

}

}

}

Example Response - Failure

The following is an example of a failed response as a result of missing the Name key.

{

"CreateResult": {

"error": {},

"response": {

"ShipTo.Create": {

"Error": "You must provide a Ship-to name."

}

}

}

}

Checking a Bill-To credit status - BillTo/CheckCredit

This function call, when called, checks the oldest outstanding order to see how many days it’s past due and check that against the Past Due Days field. If, "Include non-shipped orders in credit check (dxdflt.df_credopenso" is not selected, the call will check the oldest outstanding order that is also shipped, ignoring any non-shipped orders.

Note: As a result of the addition of this endpoint, if not using pre-payment Terms, all customers entering orders via "Cart/Checkout", "Cart/CheckoutPost", and "Cart/CreateOrder" endpoints will have their credit checked before the order is successfully placed. The order may be refused or placed on credit hold if their credit is not sufficient.

Required Parameters

  • None other than SiteID

Example Call

http://localhost:8181/BillTo/CheckCredit?SiteID=1

Example Response - Success

{

"CheckCreditResult\": {

"error": {},

"response": {

"BillTo.CheckCredit": {

"CurrentStatus": {

"OwedBalance_PendingOrders": 1250.50,

"OwedBalance_ShippedOrders": 250.0,

"OwedBalance_CurrentCart": 0.0,

"OwedBalance_Total": 1500.50,

"CurrentDaysOverdue": 0},

"CreditLimits": {

"Dollars_Limit": 2000.0,

"Dollars_NeverExceedLimit": 2500.0,

"Days_Limit": 5,

"Days_NeverExceedLimit": 10},

"ExceededLimits": {

"Dollars_PastLimit": false,

"Dollars_PastNeverExceedLimit": false,

"Days_PastLimit": false,

"Days_PastNeverExceedLimit": false},

"CreditHolds": {

"CreditHold_TotalNumberOfOrders": 0,

"CreditHold_Total": 0.0

}

}

}

}

}

}

Example Response - Failure

{

"CheckCreditResult": {

"error": {},

"response": {

"BillTo.CheckCredit": {

"Error": "Could not find a user account associated with this session."

}

}

}

}

}

Make payments on account - /BillTo/PayOnAccount

This endpoint allows eCommerce users to make payments on account for their attached Bill-To record. This performs the same functionality as the Cash Receipts page in the main application.

Parameters

  • None other than SiteID

Example Call

http://localhost:8181/BillTo/PayOnAccount

Example Response - Success

{

"PayOnAccountResult": {

"error": {},

"response": {

"BillTo.PayOnAccount": {

"Success": true,

"PaidAmount": 35,

"ConfirmationNumber": "2023-74539-00"

}

}

}

}

}

Example Response - Failure

{

"PayOnAccountResult": {

"error": {},

"response": {

"BillTo.PayOnAccount": {

"Error": "Argument Error - The [PaymentAmount] value must be greater than 0."

}

}

}

}

}

Modifying a Ship-to record - /ShipTo/Update

This function call updates a Ship-to record based on new values passed in. The Ship-to record to be updated is determined by the default Ship-to on the current session's user, or the current session's cart if no user is logged in. The following fields can currently be set by this function: sh_name, sh_street, sh_street2, sh_city, sh_state, sh_phone, sh_fax, sh_email, sh_contact, sh_country, sh_phext, sh_active, sh_poreqd, sh_credflg, sh_reqcpart, sh_credhld, sh_said, sh_dba, sh_svctype, sh_addressvalid, and all dmship user fields

Parameters

  • NewValues - A string containing the lookup of fields and new values to set. Example: [{"sh_name":"eCommerce Test - Name"}, {"sh_street":"601 Lee Rd"},{"sh_active":"true"}, {"sh_credhld":"02/20/2019"}, {"sh_dba":"dba test"},{"sh_svctype":"Business"},{"sh_addressvalid":"02/07/2020"}]
  • UserFieldValues (optional) - A string containing the lookup of user field IDs (d1_id) and values to set. Example: [{"57":"eCommerce Test"}, {"60":"100"},{"229":"Test2"}]
  • Dear (optional) - The name of the person in the Dear field (sh_dear) of the Ship-To record in DEACOM.
  • RecordID(optional) - The RecordID parameter must match one of the following: The cart's Ship-To, the user's Ship-To, a Ship-To linked to the current user's Bill-To (anything returned by User/GetShipTo), or a Ship-To that is currently set on a cart line item.

Example Call

http://localhost:8080/ShipTo/Update?RecordID=2689&NewValues=[{"sh_name":"eCommerce Test - Name"}, {"sh_street":"601 Lee Rd"},{"sh_active":"true"}, {"sh_credhld":"02/20/2019"}, {"sh_dba":"dba test"}]&UserFieldValues=[{"57":"eCommerce Test"}, {"60":"100"},{"229":"Test2"}]

Example Response - Success

{

"UpdateResult": {

"error": {},

"response": {

"ShipTo.Update": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response. An error will be returned under the following conditions:

A Ship-to could not be found for the given user/cart.

The NewValues parameter specifies a field that cannot be updated by this function.

A user field ID could not be identified.

{

"UpdateResult": {

"error": {},

"response": {

"ShipTo.Update": {

"Error": "Could not find a Ship-to customer with an ID of 1000."

}

}

}

}

Verifying Ship-to Address - /ShipTo/ValidateAddress

The ValidateAddress call checks the dxdflt3.df_dfltvalidtype value in system options to see whether to use UPS or FedEx. Next the system checks to see if the Ship-to specified contains a valid address by evaluating the fields listed in the Parameters section.

Parameters

  • Street - Street address indicated on the Ship-to record
  • Street - Street2 address indicated on the Ship-to record
  • City - City indicated on the Ship-to record
  • State - State indicated on the Ship-to record
  • Zip - Zip indicated on the Ship-to record
  • Country - Country indicated on the Ship-to record.
  • RecordID(optional) - When provided, the other address parameters are not needed and the address of the Ship-To linked to the RecordID will be validated. The RecordID must match the ID of a Ship-To linked to the current session (via the current user, cart, or cart items). The Ship-To will then have it's "last validated date" (sh_addressvalid) field filled in with today's date.

Example Calls

Fully validated addess - http://localhost:8080/ShipTo/ValidateAddress?Street=601 Lee Rd&Street2=&City=WAYNE&State=PA&Zip=19087-5607&Country=US

Address that will return the correct address - http://localhost:8080/ShipTo/ValidateAddress?Street=601 Lee Rd&Street2=&City=Chesterbrook&State=PA&Zip=19087&Country=US

Address that will fail - http://localhost:8080/ShipTo/ValidateAddress?Street=45601 Lee Rd&Street2=&City=WAYNE&State=PA&Zip=19087-5607&Country=US

Example Response - Success

{

"ValidateAddressResult": {

"error": {},

"response": {

"ShipTo.ValidateAddress": {

"Success": {

"sh_street": "601 LEE RD",

"sh_street2": "",

"sh_city": "WAYNE",

"sh_state": "PA",

"sh_zip": "19087-5607",

"sh_country": "US",

"sh_svctype": "MIXED",

"suitestatus": "missing"

}

}

}

}

}

Example Response - Failure

{

"ValidateAddressResult": {

"error": {},

"response": {

"ShipTo.ValidateAddress": {

"Error": "The address is invalid."

}

}

}

}

Obtaining Ship-to information - /ShipTo/GetData

This function has no parameters. It will identify the Ship-To ID linked to the currently logged in user (or linked to the cart if no user is logged in) and will return all dmship fields and dmship user fields for that Ship-To.

Parameters:

  • CartShipToID - Optional. The id of the cart for the selected Ship-to

Example Call

http://localhost:8181/ShipTo/GetData

Example Response - Success

{

"GetDataResult": {

"error": {},

"response": {

"ShipTo.GetData": {

"ShipTo": {

"sh_id": 2689,

"sh_name": "eCommerce Test - Matt",

"sh_street": "601 Lee Rd",

"sh_street2": "Unit A",

"sh_active": true,

"sh_trid": 12,

"sh_city": "New York",

"sh_state": "NY",

"sh_zip": "10001",

"sh_phone": "1231231234",

"sh_fax": "",

"sh_credhld": "2019-02-20T00:00:00",

"sh_credflag": false,

"sh_contact": "eCommerce",

"sh_country": "United States",

"sh_phext": "",

"sh_email": "[email protected]",

"sh_reqcpart": false,

"sh_waid": 1,

"sh_brid": 1

"sh_dear": "Mr. Smith, Tom"

}

}

}

}

}

Example Response - Failure

The below is an example of a failed call response. An error will be returned under the following conditions:

The current user does not have a default Ship-To specified (a user's default ship-to is optional).

The Ship-To linked to the user is no longer active.

{

"GetDataResult": {

"error": {},

"response": {

"ShipTo.GetData": {

"Error": "This user does not have a Ship-To ID specified."

}

}

}

}

Obtain modified Ship-To records - /ShipTo/GetModifiedRecords

This API call will obtain information on modified records from the Ship-To (dmship) table for the specified time period. (Added in version 16.07.054)

Parameters

  • Site ID (required) - the ID of the eCommerce site.

Example Call

http://localhost:8181/ShipTo/GetModifiedRecords?SiteID=1&StartDate=3/7/2022 23:59:59&EndDate=6/9/2022 17:00:00

Example Response - Success

The success response will be similar to the /General/GetModifiedRecords, but will only include information from the Ship-To (dmship) table.

Example Response - Failure

N/A - Users may receive some generic errors in the case of a failure.

Obtain information for new Ship-To records - /ShipTo/GetNewRecords

This API call will obtain information on new records added to the Ship-To (dmship) table for the specified time period. (Added in version 16.07.054)

Parameters

  • Site ID (required) - the ID of the eCommerce site.

Example Call

http://localhost:8181/ShipTo/GetNewRecords?SiteID=1&StartDate=3/7/2022 23:59:59&EndDate=6/13/2022 12:59:00

Example Response - Success

The success response will be similar to the /General/GetNewRecords, but will only include information from the Ship-To (dmship) table.

Example Response - Failure

N/A - Users may receive some generic errors in the case of a failure.

Add a Salesman Record - /Salesman/AddSalesman

The salesman object (the sm_id MUST be passed back in the return)

Required Parameters

  • Last Name: sm_lname
  • Sales Group - default to system default sales group

Optional Paramters

  • FirstName: sm_fname (default to empty)
  • Street: sm_street (default to empty)
  • City: sm_city (default to empty)
  • State: sm_state (default to empty)
  • Zip: sm_zip (default to empty)
  • Phone: sm_cphone (default to empty)
  • Vender: sm_veid (default to empty)
  • Active: sm_active (default to true)
  • UserFieldValues - User Defined Fields from the Sales Reps record.
  • UniqueFields - checks for uniqueness in User Defined Fields.

Note: In eCommerce, UDFs can now be attached to the "Salesman/AddSalesman" call in the new "UserFieldValues" parameter. It is also now possible to check UDFs for uniqueness before saving, via the "UniqueFields" parameter.

Example Call:

http://localhost:8181/Salesman/AddSalesman?SiteID=1&SalesGroup=6&LastName=Oakleys&FirstName=Robert&Street=55 John St.&Street2=Apt 502&City=New York&State=NY&Zip=10038&Phone=555-666-7777&Vendor=55&Active=true&UniqueFields=sm_lname

Example Response - Success

"AddSalesmanResult": {

"error": {},

"response": {

"Salesman.AddSalesman": {"Success": true,

"Result": {

"Salesman ID": 118,

"Sales Group ID": 6,

"First Name": "Robert",

"Last Name": "Stevenson",

"Street Address 1": "55 John St.",

"Street Address 2": "Apt 502",

"City": "New York",

"State": "NY",

"Zip Code": "10038",

"Phone": "555-666-7777",

"Vendor ID": 55,

"Active State": true

}

}

}

}

}

Example Response - Failure (UniqueFields Constraint Violated)

"AddSalesmanResult": {

"error": {},

"response": {

"Salesman.AddSalesman": {

"Error": "Constraint Violation Error - A UniqueField constraint was violated when attempting to store this Salesman data. The 'sm_lname' of 'Stevenson' is not unique."

}

}

}

}

Obtain Salesman Record - /Salesman/GetSalesman

Returns: all dmsman records that apply to the filters

Required Parameters

  • None

Optional Parameters

  • ID: sm_id (default to empty)
  • FirstName sm_fname (default to empty)
  • LastName: sm_lname (default to empty)
  • Active: sm_active (default to true)

Example Call

http://localhost:8181/Salesman/GetSalesmen?SiteID=1&ID=114

Example Response - Success

"GetSalesmenResult": {

"error": {},

"response": {

"Salesman.GetSalesmen": {

"TotalNumberOfRecords": 1,

"Success": true,

"Result": [{

"Salesman ID": 114,

"Sales Group ID": 6,

"First Name": "Steve",

"Last Name": "Brianson",

"Street Address 1": "55 John St.",

"Street Address 2": "Apt 502",

"City": "New York",

"State": "NY",

"Zip Code": "10038",

"Phone": "555-666-7777",

"Vendor ID": 55,

"Active State": true

}

]

}

}

}

}

Example Response - Failure (No Results Found)

"GetSalesmenResult": {

"error": {},

"response": {

"Salesman.GetSalesmen": {

"Error": "Argument Error - No Salesmen matching the given criteria were found."

}

}

}

}

Obtain Salesman Information - /Salesman/GetData

- Returns: all values on the dmsman record that applies to the dmsman record with id = ID. The call will include a Userfields node in this return as well for the userfields on the salesman record.

Note: The following changes were made to this call beginning in version 16.04.059.

  • Update salesman.getdata
  • Within the order history node, added a property: orderDeal
  • This will be populated as a single total of all order lines: the difference between or_lispric and or_dealpric
  • Within the order history node, added a property: orderDealPercent
  • This should be populated as a single total of all order line deal percentages - -(sum of order line or_dealpric/sum of order line or_lispric)
  • Within each “LineInfo” node, add a property: DealPercent
  • This should be calculated as follows: 1-(or_dealpric/or_lispric)

Required Paramaters

  • SalesmanID: sm_id

Example Call

http://localhost:8181/Salesman/GetData?SiteID=1&SalesmanID=1

Example Response - Success

"GetDataResult": {

"error": {},

"response": {

"Salesman.GetData": {

"Success": true,

"Result": [{

"sm_ccode": "",

"sm_eligible": true,

"sm_id": 114,

"sm_fname": "Steve",

"sm_lname": "Oak",

"sm_street": "55 John St.",

"sm_street2": "Apt 502",

"sm_city": "New York",

"sm_state": "NY",

"sm_webname": "",

"sm_webpass": "",

"sm_sgid": 6,

"sm_quota": 0,

"sm_mobileid": 0,

"sm_email": "",

"sm_zip": "10038",

"sm_hphone": "",

"sm_fax": "",

"sm_cphone": "555-666-7777",

"sm_beeper": "",

"sm_active": true,

"sm_default": false,

"sm_veid": 55,

"sm_ccid": 0,

"sm_repid": "",

"ve_name" Deacom, Inc."

}],

"UserFields": {

"114": {}

}

}

}

}

}

Example Response - Failure (Required Param Missing)

"GetDataResult": {

"error": {},

"response": {

"Salesman.GetData": {

"Error": "Argument Error - The 'SalesmanID' parameter is required, but was missing from the query. Please specify a numeric SalesmanID."

}

}

}

}

Update Salesman Record - /Salesman/Update

Required Parameters

  • SalesmanID - sm_id

Optional Parameters

  • LastName: sm_lname: if this is passed, update the value for sm_lname
  • UserDefinedFields - This parameter can be used to set the UDFs on the Salesman object. The "UniqueFields" parameter that already exists can now be used to check for uniqueness in the UDFs. In addition, "Salesman/GetSalesmen" API endpoint can retrieve Salesman objects based on UDFs.

Example Call

http://localhost:8181/Salesman/Update?SiteID=1&SalesmanID=1125&NewValues=[{'sm_lname':'Kinsleyson'},{'sm_cphone':'570-999-9999'}]&UniqueFields=sm_lname

Example Response - Success

"UpdateResult": {

"error": {},

"response": {

"Salesman.Update": {

"Success": true,

"Result": "Update succeeded"

}

}

}

}

Example Repsponse - Failure (Required Param Missing)

"UpdateResult": {

"error": {},

"response": {

"Salesman.Update": {

"Error": "Argument Error - The 'SalesmanID' parameter is required, but was missing from the query. Please specify a numeric SalesmanID."

}

}

}

}

Return Salesman Sales Orders - /Salesman/GetOrder

Returns: All orders attributed to this salesman. Return the same output style as User.GetOrder. The call will ensure that the deal pricing percentage for each order is included. Beginning in version 16.04.058 this call is filterable and paginated with the inclusion of the optional parameters listed below.

Required Parameters

  • SalesmanID: sm_id

Optional Parameters

  • PageNumber: Integer. Corresponds to the page count in the pagination. Specifies which block of orders, specified by NumberOfItemsPerPage, to return.
  • NumberOfItemsPerPage: Integer. How many orders to return on a given page.
  • ReturnAllOrders: Boolean. Defaults to false. If true, ignores all pagination related parameters and returns ALL orders for the salesman on one page.
  • OrderByAsc: Boolean. Defaults to false. If true, sorts the results by the criteria specified, in ascending order. If false, the results will be in descending order. The default criteria to sort by is to_ordnum.
  • InclusionFilter - used to filter for orders with a to_paydate of 'NULL'. See example call below for details. This parameter supports the ability to generate customer statements via the User/GetStatement call. Added in version 16.04.122.
  • ExclusionFilter - used to filter out orders with a to_paydate of 'NULL'.
  • SortByOrderDate: Boolean. Defaults to false. If true, changes the sorting criteria to sort by the Order Date. The direction of the sort can still be controlled by OrderByAsc.
  • OrderNumber: String. When passed, will filter the resulting orders to ONLY contain the single order with a to_ordnum that matches the query. If the order was not found in the Salesman's orders, you will get 0 results.

NOTE: If using this parameter, pagination related parameters should not be passed at all, OR ReturnAllOrders should be set to 'true'. (This behavior is similar to User.GetOrder. If pagination is specified, only the active page will be searched for the results. This is undesirable, so pagination should not be set when using this parameter.)

  • GetDealEarnings:* -used to return earnings for Sales Deals.
  • DealEarningsStartDate:* - sales Deal earning start date.
  • DealEarningEndDate:* - sales Deal earning end date.

*These parameters are used to calculate the earnings of a salesman for a particular date range (when those earnings are based on markup deals). The earned amount for the given time frame is represented as a JSON node named "Earnings" in the response.

Additional Notes:

  • The following changes were made to this call beginning in version 16.04.059.
  • Update GetOrder
  • Ensure or_dealpric is shown within the “LineInfo” (may have to add this to the order model)
  • Add deals linked to this order by way of the salesman
  • Add commission
  • Version 16.04.128 introduces a new security improvement for this call which prevents unauthorized access to user orders. Details:
  • To use this endpoint, a standardized UDF with the name "u_salesman_admin" must exist in the system. The currently logged in eCommerce user must also have a Salesman object assigned for this user defined field.
  • When calling "Salesman/GetOrder", orders corresponding to the "u_salesman_admin" UDF on the currently logged in user will be returned. The ability to specify a "SalesmanID" parameter has been removed.
  • Beginning in version 17.02.014, this endpoint will now return earnings data and the total number of orders that the salesman has participated in, even if the current user is a guest or is not associated with that salesman. In this case, order data is not returned, since the user is not authenticated to read sensitive order information.

Example Call

http://localhost:8181/Salesman/GetOrder?SiteID=1&SalesmanID=1

Example Response - Success

"GetOrderResult": {

"error": {},

"response": {

"Salesman.GetOrder": {

"TotalNumberOfRecords": 5,

"Success": true,

"Orders": [{

"Order": {

"OrderHistory": {

"to_ordnum": "2018-33670-00",

"to_id": 224974,

"to_orddate": "03/07/2018",

"orderSubtotal": "$0.00",

"to_totdue": "$0.00",

"paymentType": "",

"shippingStatus": "Shipped on 03/15/2018",

"shippingCost": 0,

"orderTax": 0,

"to_notes": "Bulk Sample Order",

"orderPromo": 0,

"to_billpo": "Bulk Sample Cathy"},

"BillTo": {

"bi_id": 24144,

"bi_name": "Frutarom USA Inc.",

"bi_active": true,

"bi_street": "5404 Duff Drive",

"bi_street2": "",

"bi_city": "Cincinnati",

"bi_state": "OH",

"bi_zip": "45246",

"bi_phone": "513-476-5341",

"bi_fax": "",

}

]

}

}

}

}

Example Response - Failure (Required Param Missing)

"GetOrderResult": {

"error": {},

"response": {

"Salesman.GetOrder": {

"Error": "Argument Error - The 'SalesmanID' parameter is required, but was missing from the query. Please specify a numeric SalesmanID."

}

}

}

}

Obtain Sales Group Information - /Salesman/GetSalesGroups

Returns: all sales groups saved in the main application with their id and description/name

Required parameters

  • none

Optional Parameters

  • Name: search by sg_name

Example Call

http://localhost:8181/Salesman/GetSalesGroups?SiteID=1&Name=

Example Response - Success

GetSalesGroupsResult": {

"error": {},

"response": {

"Salesman.GetSalesGroups": {

"TotalNumberOfRecords": 3,

"Success": true,

"Result": [

{

"sg_id": 1,

"sg_name": "Default",

"sg_quota": 0,

"sg_default": true,

"sg_active": true},

{ "sg_id": 2,

"sg_name": "IC Transfer",

"sg_quota": 0,

"sg_default": false,

"sg_active": true},

{ "sg_id": 3,

"sg_name": "Fundraising",

"sg_quota": 0,

"sg_default": false,

"sg_active": true

}

]

}

}

}

}

Example Response - Failure (No Results Found)

"GetSalesGroupsResult": {

"error": {},

"response": {

"Salesman.GetSalesGroups": {

"Error": "Argument Error - No Sales Groups exist with an 'sg_name' field matching the provided 'Name' parameter."

}

}

}

}

Add Bill-To Sales Assignments - /BillTo/AddSalesAssignment

Required Parameters

  • SalesmanID: dmd1.s1_id

Optional Parameters

  • RecordID: Bill-To bi_id (allow fetching from logged-in user if applicable)
  • Percentage: default to 100%
  • Primary: s2_primary: default to no

Example Call

http://localhost:8181/BillTo/AddSalesAssignment?SiteID=1&SalesmanID=45&RecordID=28729&Percentage=100&Primary=false

Example Response - Success

"AddSalesAssignmentResult": {

"error": {},

"response": {

"BillTo.AddSalesAssignment": {

"Success": true,

"Result": {

"Sales Assignment ID": 1286429,

"Sales Assignment Commission Percent": 100,

"Sales Assignment Category ID": 0,

"Sales Assignment Primary Status": false,

"Change to Shipping": false,

"Bill-To ID": 28729,

"Bill-To Name": "Gary Myers",

"Salesman ID": 110,

"Salesman First Name": "Ryan",

"Salesman Last Name": "OHara",

"Salesman Active State": true

}

}

}

}

}

Example Response - Failure (Required Param Missing)

"AddSalesAssignmentResult": {

"error": {},

"response": {

"BillTo.AddSalesAssignment": {

"Error": "Argument Error - The 'SalesmanID' parameter is required, but was missing from the query. Please specify a numeric SalesmanID."

}

}

}

}

Return Bill-To Sales Assignments - /BillTo/GetSalesAssignments

- Returns: All Sales assignments on the bill-to (it will not check for active flags on the salesmen attached)

Required Parameters

  • None

Optional Parameters

  • RecordID: Bill-To bi_id (allow fetching from logged-in user if applicable)
  • Active: sm_active (default to false) - when true, filter out only assignments where the linked salesman is active

Example Call

http://localhost:8181/BillTo/GetSalesAssignments?SiteID=1&RecordID=28729

Example Response - Success

"GetSalesAssignmentsResult": {

"error": {},

"response": {

"BillTo.GetSalesAssignments": {

"TotalNumberOfRecords": 10,

"Success": true,

"Result": [

{

"bi_name":

"Gary Myers",

"bi_id": 28729,

"sm_fname": "",

"sm_lname": "001 Terri Lynn",

"sm_active": true,

"s2_primary": true,

"s2_id": 1265092,

"s2_smid": 4,

"s2_pct": 100,

"s2_changeuser": false,

"s2_scid": 0 },

{"bi_name": "Gary Myers",

"bi_id": 28729,

"sm_fname": "",

"sm_lname": "001 Terri Lynn",

"sm_active": true,

"s2_primary": false,

"s2_id": 1286421,

"s2_smid": 4,

"s2_pct": 100,

"s2_changeuser": false,

}

]

}

}

}

Example Response - Failure (No Results Found)

"GetSalesAssignmentsResult": {

"error": {},

"response": {

"BillTo.GetSalesAssignments": {

"Error": "Argument Error - The Bill-To passed in the 'RecordID' field does not exist."

}

}

}

}

Deactivate Bill-To Record - /BillTo/DeactiveBillTo

Returns: Success result (true/false) if the billto was already deactivated, and let the user know this.

Required Parameters

  • None

Optional Parameters

  • BillToID: links to bi_id. If passed, deactivate this bill-to. Otherwise get the logged-in bill-to with BillTo.GetBillTo(poSession) and deactivate that one

Ensure that the bill-to is deactivated for both <companydb>.dmcmsuseracc

Example Call

http://localhost:8181/BillTo/DeactivateBillTo?SiteID=1&BillToID=28729

Example Response - Success

"DeactivateBillToResult": {

"error": {},

"response": {

"BillTo.DeactivateBillTo": {

"Success": true,

"Result": "Deactivation succeeded"

}

}

}

}

Example Response - Failure (Bill-To Already Deactivated)

"DeactivateBillToResult": {

"error": {},

"response": {

"BillTo.DeactivateBillTo": {

"Error": "Argument Error - The selected Bill-To Company is already deactivated."

}

}

}

}

Add Sales Assignment To Carts - /Cart/AddSalesAssignment

This call allow for manually setting sales assignments on the Cart Model. When the user sends a call to this endpoint, the system will add the sales assignment to the cart model list. Note: On checkout the sales assignments added to the cart will be applied first instead of site/ship-to defaults.

Parameters:

  • SalesmanID (required) - system ID of the salesmen record from the dmsman2 table
  • Percentage (required) - The sales commission percentage

Example Call:

http://localhost:8181/Cart/AddSalesAssignment?SalesmanID=4&Percentage=100

Example Response - Success

{

"AddSalesAssignmentResult": {

"error": {},

"response": {

"Cart.AddSalesAssignment": {

"success": true

}

}

}

}

Example Response - Failure (Sales Assignments greater than 100 percent)

{

"AddSalesAssignmentResult": {

"error": {

"type": "nonFatal",

"exceptionType": "DeacomException",

"message": "Cannot have total sales assignment percentage greater than 100"

},

"response": {}

}

}

Handling User Fields

Obtaining User Field names - /General/GetUserFields

This call returns user field names and corresponding IDs.

Parameters:

Both are optional, but at least one must be specified. If RecordID is provided, a single user field/ID will be returned; otherwise all user fields will be returned for the given Table.

  • Table - the table to gather User Fields from
  • RecordID - the specific User Field ID

Example Call:

http://localhost:8080/General/GetUserFields?RecordID=403&Table=dmprod

Example Response - Success

{

"GetUserFieldsResult": {

"error": {},

"response": {

"General.GetUserFields": {

"Success": true,

"Results": {

"Volume Discount Quantity": 403

}

}

}

}

}

Example Response - Failure - No User Field Found

{

"GetUserFieldsResult": {

"error": {},

"response": {

"General.GetUserFields": {

"Error": "Could not find any user fields for the given criteria."

}

}

}

}

Obtaining User Field values - /General/GetUserFieldValues

This call returns current user field values for a given Record ID, User Field ID, or Table.

Parameters:

The UserFieldID and Table parameters are both optional, but at least one of the two must be provided. If a UserFieldID is provided, only a single value will be returned; otherwise all user field values for a given RecordID and Table will be provided.

  • RecordID - the parent record ID
  • UserFieldID - the d1_id of the user field to get the value of
  • Table - the table that the RecordID corresponds to

Example Call:

http://localhost:8080/General/GetUserFieldValues?UserFieldID=25&RecordID=5356&Table=dmprod

Example Response - Success

{

"GetUserFieldValuesResult": {

"error": {},

"response": {

"General.GetUserFieldValues": {

"Success": true,

"Results": {

"davetest": "Testing123"

}

}

}

}

}

Example Response - Failure - No User Field Data Found

{

"GetUserFieldValuesResult": {

"error": {},

"response": {

"General.GetUserFieldValues": {

"Error": "No user field data could be found for the given parameters."

}

}

}

}

Setting a User Field value - /General/SetUserFieldValue

This call sets a User Field value based on the provided parameters.

Parameters:

  • UserFieldID - the d1_id of the user field to get the value of
  • RecordID - the parent record ID to set the field on
  • NewValue - the value to set the user field to; if no NewValue parameter is specified, an existing user field value for that UserFieldID/RecordID will be cleared.
  • IsCartUserField(optional) - defaults to false. This value should be true any time a user field should be set on a cart (i.e. any time before checkout). Failing to set this parameter to true before checkout runs the risk of setting a user field value on an already-completed order in main app.

Example Call:

http://localhost:8080/General/SetUserFieldValue?UserFieldID=25&RecordID=5356&NewValue=Testing123

Example Response - Success

{

"SetUserFieldValueResult": {

"error": {},

"response": {

"General.SetUserFieldValue": {

"Success": true

}

}

}

}

Example Response - Failure - No Record ID provided

{

"SetUserFieldValueResult": {

"error": {},

"response": {

"General.SetUserFieldValue": {

"Error": "You must provide a RecordID."

}

}

}

}

Setting multiple User Field values - /General/SetUserFieldValues

This call sets new values for multiple User Fields at once.

Parameters:

  • RecordID - the parent record ID to set the fields on
  • NewValues - a string lookup containing the d1_id and new value pairings.
    • Example: [{"25":"eCommerce Test"}, {"26":"Two"},{"32":"5.7"}]; This parameter matches each d1_id (ex: 25) to the intended new value (ex: "eCommerce Test"). User Field and value pairs are each surrounded by curly braces {} and multiple pairs are split via commas.
  • IsCartUserField(optional) - defaults to false. This value should be true any time a user field should be set on a cart (i.e. any time before checkout). Failing to set this parameter to true before checkout runs the risk of setting a user field value on an already-completed order in main app.

Example Call:

http://localhost:8080/General/SetUserFieldValues?RecordID=5356&NewValues=[{"25":"eCommerce Test"}, {"26":"Two"},{"32":"5.7"}, {"35":"02/06/2019"}]

Example Response - Success

{

"SetUserFieldValuesResult": {

"error": {},

"response": {

"General.SetUserFieldValues": {

"Success": true

}

}

}

}

Example Response - Failure - No Record ID provided

{

"SetUserFieldValuesResult": {

"error": {},

"response": {

"General.SetUserFieldValues": {

"Error": "You must provide a RecordID."

}

}

}

}

Retrieve historical records for userfield values - /General/GetHistoricalUDFValues

This API returns the histroical values for User Defined Fields in DEACOM.

Required Parameters

  • RecordID: Salesman ID (dmsman.sm_id)
  • KeyUDFID: (int, id) The udf who's change calls us to consider it a new record
  • EndingValueUDFIDs: (list int, ids) The other UDFs that we're interested in seeing a value "snapshot" of

Example Call

localhost:8181/General/GetHistoricalUDFValues?SiteID=1&RecordID=4&KeyUDFID=1094&EndingValueUDFIDs=2098, 2099, 1095

Note: There should be two nodes in this return. CurrentValues AND HistoricalValues. The current values can be found in dtd2 and should not be replicated in the historical values node. Before returning the HistoricalValues node, the call should filter out any records where all values except active are the same and return only the most recent of them (dxmod has a time field)

Example Response - Success

{

"GetHistoricalUDFValuesResult": {

"error": {},

"response": {

"General.GetHistoricalUDFValues": {

"Result": {

"CurrentValues": {1},

"HistoricalValues": {0

"Snapshot 1": {

"UDFs": {},

"Key UDF Edit Timestamp": "1/3/2020 13:58:30"

}

}

}

}

}

}

}

Example Response - Failure - Invalid UDF ID

{

"GetHistoricalUDFValuesResult": {

"error": {},

"response": {

"General.GetHistoricalUDFValues": {

"Error": "Argument Error - No UDF entries could be found based on the chosen parameters. Please check your arguments."

}

}

}

}

Query for Customers by External ID user field - /General/GetRecordIDByUserFieldIDAndValue

When this API is called, the system will return the dtd2.d2_recid associated with the dtd2 record returned. The call will return 0 if there is nothing found matching the ID and value, e.g.: {RecordID = ##}

Parameters

  • ID (required) - dmd1.d1_id of the user field being specified.
  • Value (required) - the dtd2.d2_value of that user field.

Example Call

http://localhost:8181/General/GetRecordIDByUserFieldIDAndValue?ID=8&Value=AMERICAN PARKING

Example Response - Success

{

"GetRecordIDByUserFieldIDAndValueResult": {

"error": {},

"response": {

"General.GetRecordIDByUserFieldIDAndValue": {

"Success": true,

"RecordID": 5.0

}

}

}

}

Example Response - Failure

The below is an example of a failed call repsonse as a result of no records matching the ID and value.

{

"GetRecordIDByUserFieldIDAndValueResult": {

"error": {},

"response": {

"General.GetRecordIDByUserFieldIDAndValue": {

"Success": true,

"RecordID": 0.0

}

}

}

}

Configuring a Cart

The cart must first be created using the Cart.Create call. Afterwards, a delivery date may be specified, items and corresponding quantities and promotions can be added, updated and deleted, Ship-to Companies and PO Numbers can be assigned, etc. Once a specific user is assigned to the cart by logging into the site, any applicable variables will update (Broker assigned, Ship-to updated, email retained for order confirmation, etc.).

Creating the cart - /Cart/Create

For this action, this call will be used to create a cart.

Example Call

http://localhost:8080/Cart/Create

Example Response - Success

The below is an example of a successful call response. In this example a cart was created but no user ID was included in the call.

{

"CreateResult": {

"error": {},

"response": {

"Cart.Create": {

"Success": {

"ca_id": 2134,

"ca_date": "09/18/2019 11:57:16",

"ca_uaid": 0,

"ca_numitem": 0,

"ca_total": 0.0,

"ca_current": true,

"ca_active": true,

"ca_shid": 0,

"ca_ponum": "",

"ca_sessionid": "4043699458a34b99854f2473b6d4996f",

"ca_name": "",

"ca_brid": 0,

"ca_notes": "",

"ca_deliverydate": "09/18/2019",

"ca_weight": 0.0,

"ca_tax": 0.0,

"ca_biid": 0,

"ca_trid": 0,

"CartItems": []

}

}

}

}

}

Example Response - Failure

The below is an example of a failed call response. Since this call is fairly basic (it does not specify a Cart ID, Part, or User - that will come later), there are not many things that can go wrong, unless the call is written incorrectly or the wrong IP Address was used. An incorrect call error would result in something like the following.

/Cart/Create refers to a path that does not exist.

Setting a delivery date - /Cart/SetDeliveryDate

Once a cart is created, this call will be used to set a delivery date for the order. Beginning in version 16.05.116, if the delivery date field on the cart is populated during checkout, that date will be saved on the resulting Sales Order in the Due to Ship ("to_dueship") field.

Parameters

DeliveryDate - the delivery date in MM/DD/YYYY format

Example Call

http://localhost:8080/Cart/SetDeliveryDate?DeliveryDate=MM/DD/YYYY

Example Response - Success

{

"SetDeliveryDateResult": {

"error": {},

"response": {

"Cart.SetDeliveryDate": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid date.

{

"SetDeliveryDateResult": {

"error": {},

"response": {

"Cart.SetDeliveryDate": {

"Error": "Date can not be less than today."

}

}

}

}

Adding items and applying promotions to the cart

Once a cart is configured, the user's standard order and other items may be added to it. In addition, promotions may be applied depending on the promotion configuration and the items, quantities, and/or prices in the cart.

Adding a standard order to a cart - /Cart/AddStandardOrderToCart

If a user has a standard order that they regularly place, this call will be used to add the parts of the standard order to the cart.

Example Call

http://localhost:8080/Cart/AddStandardOrderToCart

Example Response - Success

The below is an example of a successful call response.

{

"AddStandardOrderToCartResult": {

"error": {},

"response": {

"Cart.AddStandardOrderToCart": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of the specified user not having a standard order.

{

"AddStandardOrderToCartResult": {

"error": {},

"response": {

"Cart.AddStandardOrderToCart": {

"Error": "There is no standard order or there are no items in the standard order."

}

}

}

}

Adding an item to a cart - /Cart/AddTo

Once a cart is created, this call will be used to add an item to the cart. Three fields are returned as a result of the call:

  • pr_codenum -- the Part number of the cart item
  • ct_prid -- the Part ID of the cart item
  • ct_shid -- the Ship-to ID of the cart item. Note that this field will only ever populate with a value if the Default Order Type (found in Tools > Tools Maintenance > eCommerce Sites) is set to 'Master Order', as basic Sales Orders will inherit ship-to data from the User/Cart by default.

This call will enforce the "Bill-To/Ship-To Cross Ref Required For Sales" flag on the DEACOM item master record. If a user selects an item with this flag checked, the system will verify that a customer part cross reference exists for the customer logged into the eCommerce site and the selected item. If a match is not found an error will be returned and the call will not be applied. Companies may need to code their front end to display the appropriate message in this situation.

Notes:

  • The ca_numitem field in this call tracks the total amount of items ordered.
  • When adding items to an eCommerce cart, if there is not enough of the item on hand to satisfy the order (including copies of the item already in the cart), the Cart/AddTo endpoint will throw an error and refuse to add the item to the cart.
  • If companies wish to allow customers the ability to add items with 0 on hand quantity to their cart(s), then the "Use MRP For On Hand Quantities" flag via Tools > Maintenance > eCommerce Sites must be unchecked. This allows items to be added to the cart and purchased regardless of quantity available.

Parameters

  • PartID - the Part ID from DEACOM
  • Quantity - the number of units of the part being added
  • NewLine - boolean. Defaults to False. If the NewLine parameter is passed into this call as True, a new cart item record will be created for the call being made. If it is not passed in or is passed in as False, a new cart item record will not be created and the system will increase the existing record for the same part. If it is passed in as TRUE and there is no cart item record with the same part number, a new cart item record will be created anyways.
  • ShipToID - the ID of the Ship-To Company for the cart item (optional parameter)
  • DeliveryDate - date of delivery (optional parameter)
  • ShipViaID - ID of the Ship Via Method for the line (optional parameter)
  • Notes - text field (optional parameter) Used to set notes the cart item level. Cart item notes are carried over to the sales order line notes field (or_notes) when syncing orders to DEACOM at checkout.
  • UserFieldValues(optional) - sets user fields on a cart item during the add process. This parameter should be formatted so that each user field and value pair is as follows:
    • {"user field ID (d1_id)":"value"} An example of this is as follows: [{"42":"test"},{"55":"80"}] In this example, the user field with IDs of 42 and 55 are set the values of "test" and "80", respectively. Each value should be surrounded by curly braces { } and the entire parameter should be wrapped in square braces [ ].

Example Call

http://localhost:8080/Cart/AddTo?PartID=YYYY&Quantity=Z

Example Response - Success

The below is an example of a successful call response.

{

"Cart.AddTo": {

"Success": true,

"Cart": {

"ca_id": 2389,

"ca_date": "7/17/2019 3:02:35 PM",

"ca_uaid": 2036,

"ca_numitem": 1,

"ca_total": 90.00,

"ca_current": true,

"ca_active": true,

"ca_shid": 2689,

"ca_ponum": "",

"ca_sessionid": "0aa3826f320441f4a8cc948c106c4797",

"ca_name": "",

"ca_brid": 0,

"ca_notes": "",

"ca_deliverydate": "07/17/2019",

"ca_weight": 39.4500000000,

"ca_tax": 0.0,

"ca_biid": 2136,

"ca_trid": 12,

"CartItems": [{

"ct_id": 2264,

"ct_caid": 2389,

"ct_prid": 3700,

"ct_ordquant": 3,

"ct_confirmnum": "",

"ct_pmid": 0,

"ct_price": 30.0000000,

"ct_shid": 2689,

"ct_trid": 12,

"ct_frid": 0,

"pr_codenum": "FINI1"

}]

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid Part ID.

{

"AddToResult": {

"error": {},

"response": {

"Cart.AddTo": {

"Error": "Part does not exist."

}

}

}

}

Adding multiple items to a cart - /Cart/AddMultiple

Once a cart is created, this call will be used to add multiple items to the cart at once rather than needing to call Cart.AddTo multiple times.

This call will enforce the "Bill-To/Ship-To Cross Ref Required For Sales" flag on the DEACOM item master record. If a user selects an item with this flag checked, the system will verify that a customer part cross reference exists for the customer logged into the eCommerce site and the selected item. If a match is not found an error will be returned and the call will not be applied. Companies may need to code their front end to display the appropriate message in this situation.

The returned JSON for this call contains a property called "TotalNumberOfItems" that displays the final summed quantity of all items that exist in the Cart. This will display in the results as a sister node to the "Success" and "Cart" node.

Notes:

  • The ca_numitem field in this call tracks the total amount of items ordered.
  • If companies wish to allow customers the ability to add items with 0 on hand quantity to their cart(s), then the "Use MRP For On Hand Quantities" flag via Tools > Maintenance > eCommerce Sites must be unchecked. This allows items to be added to the cart and purchased regardless of quantity available.
  • The call will be prevented from executing if the value in the "Maximum Cart Value" field (cs_maxcartvalue) is exceeded.

Parameters

A dictionary of Part ID(s) and quantities. For example, using a dictionary of [{"3717":"3"}, {"4042":"5"}] indicates two lines are being added, one for 3 units of part id 3717 and a second for 5 units of part id 4042

  • NewLine - boolean. Defaults to False. If the NewLine parameter is passed into this call as True, a new cart item record will be created for the call being made. If it is not passed in or is passed in as False, a new cart item record will not be created and the system will increase the existing record for the same part. If it is passed in as TRUE and there is no cart item record with the same part number, a new cart item record will be created anyways.
  • ShipToID - the ID of the Ship-To Company for the cart item (optional parameter)
  • DeliveryDate - date of delivery (optional parameter)
  • ShipViaID - ID of the Ship Via Method for the line (optional parameter)
  • Notes - text field (optional parameter) Used to set notes the cart item level. Cart item notes are carried over to the sales order line notes field (or_notes) when syncing orders to DEACOM at checkout.
  • UserFieldValues(optional) - sets user fields on a cart item during the add process. Note that using this parameter in the Cart/AddMultiple call will set the same user field values for ALL items being added to the cart in that transaction.This parameter should be formatted so that each user field and value pair is as follows:
    • {"user field ID (d1_id)":"value"} An example of this is as follows: [{"42":"test"},{"55":"80"}] In this example, the user field with IDs of 42 and 55 are set the values of "test" and "80", respectively. Each value should be surrounded by curly braces { } and the entire parameter should be wrapped in square braces [ ].

Example Call

http://localhost:8181/Cart/AddMultiple?Parts=[{"YYYY ":"A"}, {"ZZZZ":"B"}]

Example Response - Success

The below is an example of a successful call response.

{

"Cart.AddMultiple": {

"Success": true,

"Cart": {

"ca_id": 2319,

"ca_date": "5/29/2019 11:30:21 AM",

"ca_uaid": 10,

"ca_numitem": 4,

"ca_total": 217.30,

"ca_current": true,

"ca_active": true,

"ca_shid": 2698,

"ca_ponum": "",

"ca_sessionid": "a6964b9b161f4223b228ead7a8a2b0c9",

"ca_name": "",

"ca_brid": 4,

"ca_notes": "",

"ca_deliverydate": "05/29/2019",

"ca_weight": 93.9000000000,

"ca_tax": 12.30,

"ca_biid": 977,

"ca_trid": 12,

"CartItems": [{

"ct_id": 2209,

"ct_caid": 2319,

"ct_prid": 3700,

"ct_ordquant": 6,

"ct_confirmnum": "",

"ct_pmid": 0,

"ct_price": 30.00,

"ct_shid": 2689,

"ct_trid": 12,

"ct_frid": 0,

"pr_codenum": "FINI1"

},

{

"ct_id": 2210,

"ct_caid": 2319,

"ct_prid": 4357,

"ct_ordquant": 10,

"ct_confirmnum": "",

"ct_pmid": 0,

"ct_price": 2.50,

"ct_shid": 2689,

"ct_trid": 12,

"ct_frid": 0,

"pr_codenum": "Raw1"

}

]

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of a quantity of 0 being provided for an item or an invalid or inactive part ID.

{

"AddMultipleResult": {

"error": {},

"response": {

"Cart.AddMultiple": {

"Error": "Can not add an item to the cart with a quantity of 0."

}

}

}

}

Adding all order contents to a cart - /Cart/CreateOrderDetails

This call defines or adds the entire contents of an order to a cart without actually checking out. This differs from the /Cart/CreateOrder call which bypasses adding items to a cart and immediately checks out with the passed-in contents.

Required Parameters

Order Header - a string containing the contents of the order header. The following order header fields can be specified in this parameter:

  • biid - the Bill-To ID
  • shid - the Ship-To ID
  • trid - the Ship Via method ID
  • brid(optional) - the Broker ID, if any
  • deliverydate - the desired delivery date of the order. Note: Beginning in version 16.05.116, if the delivery date field on the cart is populated during checkout, that date will be saved on the resulting Sales Order in the Due to Ship ("to_dueship") field.
  • notes(optional) - the order header notes, if any
  • ponum(optional) - the Bill-To company PO, if any

Note: The OrderHeader parameter should be formatted as "field":value, "field":value, with curly braces {} surrounding it, in order to be parsed properly. Example: {"biid":2218,"shid":2698,"trid":6,"brid":0,"deliverydate":"02/01/2020","notes":"Test Note","ponum":"Test ponum"}

Order Lines - a string containing the contents of the order lines. The following order line fields can be specified in this parameter:

  • prid - the Part ID
  • quant - the quantity being ordered
  • notes(optional) - the notes for this part, if any
  • shid (optional) -- the Ship-To ID of the item. Master Orders only.
  • trid (optional) -- the Ship Via method ID. Master Orders only.
  • deliverydate (optional) -- the desired delivery date of the item. Master Orders only.
    • (numeric user field IDs, optional) -- user field values can also be set within the OrderLines parameter by specifying the ID (dmd1.d1_id) of the user field you wish to apply. This works similarly to how the UserFieldValues parameter is used in Cart/AddTo and Cart/AddMultiple, except that in this case the user field specification is merged to be within the OrderLines parameter.

Note: The OrderLines parameter should be formatted with each order line designated as "field":value, "field":value. Each order line should be surrounded by curly braces {} with the entire parameter enclosed in square braces []. Example: [{"prid":3700,"quant":2,"notes":"TestNote","shid":2812,"trid":6,"deliverydate":"07/01/2020","42":"Test1","55":"123"},{"prid":3700,"quant":1,"notes":"TestNote2","shid":2822,"trid":6,"deliverydate":"07/05/2020","42":"Test2","55":"456"}]

Optional Parameters

  • NewCart - Boolean value to represent whether a new cart should be created when this function is called. This parameter defaults as false and expects the user to have already created a cart (Cart/Create) and optional logged in a user (User/Login) beforehand in this case. When true, a new cart will be created using the same criteria that Cart/Create uses. Note that any existing carts linked to the session will be overwritten when NewCart = true.
  • Version Note: Beginning in version 16.04.112 (and higher), the following Cart Item fields have been removed: "IsCalcItem", "IsManualTaxItem", and "IsFreightOrShippingItem". They have been replaced with a new string property called "ItemClassification". This is an enum which can contain the following values, which are automatically selected based on the item's type: "Product", "Promotion", "Shipping", "Tax", and "UserCalculation". This change enables the front-end developers to read a consistent node which describes how the item should behave. The "Cart/GetCartItems" JSON has also been cleaned up.

Example Call

http://localhost:8181/Cart/CreateOrderDetails?OrderHeader={"biid":2235,"shid":2812,"trid":6,"brid":1,"deliverydate":"07/01/2020","notes":"Test Note","ponum":"Test ponum","12":25,"16":"Header UDF Value"}&OrderLines=[{"prid":3700,"quant":2,"notes":"TestNote","shid":2812,"trid":6,"deliverydate":"07/01/2020","42":"Test1","55":"123"},{"prid":3700,"quant":1,"notes":"TestNote2","shid":2822,"trid":6,"deliverydate":"07/05/2020","42":"Test2","55":"456"}]&NewCart=true

Example Response - Success

The below is an example of a successful call response.

{

"CreateOrderDetailsResult": {

"error": {},

"response": {

"Cart.CreateOrderDetails": {

"Success": true,

"Cart": {

"ca_id": 3018,

"ca_date": "6/12/2020 2:09:12 PM",

"ca_uaid": 0,

"ca_numitem": 5,

"ca_total": 105.5,

"ca_current": true,

"ca_active": true,

"ca_shid": 2812,

"ca_ponum": "Test ponum",

"ca_sessionid": "aff57abab5c649589a70aff4899db28d",

"ca_name": "",

"ca_brid": 1,

"ca_notes": "Test Note",

"ca_deliverydate": "07/01/2020",

"ca_weight": 39.45,

"ca_tax": 3.6,

"ca_biid": 2235,

"ca_trid": 6,

"ca_ipaddress": "127.0.0.1",

"ca_ordnum": 0.0,

"CartItems": [

{

"ct_id": 3582,

"ct_caid": 3018,

"ct_prid": 3700,

"ct_ordquant": 2,

"ct_confirmnum": "",

"ct_pmid": 0,

"ct_price": 30.0,

"ct_shid": 2812,

"ct_trid": 6,

"ct_frid": 0,

"ct_notes": "TestNote",

"ct_deldate": "2020-07-01T00:00:00",

"SalesFactor": 1.0,

"Extension": 60.0,

"pr_codenum": "FINI1",

"IsCalcItem": false

},

{

"ct_id": 3583,

"ct_caid": 3018,

"ct_prid": 3700,

"ct_ordquant": 1,

"ct_confirmnum": "",

"ct_pmid": 0,

"ct_price": 30.0,

"ct_shid": 2822,

"ct_trid": 6,

"ct_frid": 0,

"ct_notes": "TestNote2",

"ct_deldate": "2020-07-05T00:00:00",

"SalesFactor": 1.0,

"Extension": 30.0,

"pr_codenum": "FINI1",

"IsCalcItem": false

},

{

"ct_id": 3584,

"ct_caid": 3018,

"ct_prid": 3872,

"ct_ordquant": 1,

"ct_confirmnum": "",

"ct_pmid": 0,

"ct_price": 5.95,

"ct_shid": 2812,

"ct_trid": 6,

"ct_frid": 0,

"ct_notes": " ",

"ct_deldate": "2020-07-01T00:00:00",

"SalesFactor": 1.0,

"Extension": 5.95,

"pr_codenum": "Freight",

"IsCalcItem": true

},

{

"ct_id": 3585,

"ct_caid": 3018,

"ct_prid": 3872,

"ct_ordquant": 1,

"ct_confirmnum": "",

"ct_pmid": 0,

"ct_price": 5.95,

"ct_shid": 2822,

"ct_trid": 6,

"ct_frid": 0,

"ct_notes": " ",

"ct_deldate": "2020-07-05T00:00:00",

"SalesFactor": 1.0,

"Extension": 5.95,

"pr_codenum": "Freight",

"IsCalcItem": true

}

]

}

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid Bill-To number.

{

"CreateOrderDetailsResult": {

"error": {},

"response": {

"Cart.CreateOrderDetails": {

"Error": "Could not determine an active Bill-To for the given ID."

}

}

}

}

Applying a promotion to a cart - /Cart/ApplyPromo

Once a cart has one or more items in it, this call will be used to apply an active promotion to the cart.

Parameters

  • PromoID(optional) - the Promotion ID from DEACOM
  • PromoDescription(optional) - The Promotion description from DEACOM

Note: One of the above parameters must be specified in order for the API call to work.

Example Call

http://localhost:8080/Cart/ApplyPromo?PromoID=Y

Example Response - Success

The below is an example of a successful call response.

{

"ApplyPromoResult": {

"error": {},

"response": {

"Cart.ApplyPromo": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid promotion.

{

"ApplyPromoResult": {

"error": {},

"response": {

"Cart.ApplyPromo": {

"Error": "Not a valid promo."

}

}

}

}

Cart Ship-To Information - /Cart/GetShipTo

This endpoint outputs information corresponding to the Ship-To on the ca_shid property of the Cart.

Required Parameters

  • SiteID - The SiteID indicates the ID number for the site. The Site ID can be obtained from the "cs_id" field on the cmssite grid.

Note: the sh_contact field was added to this endpoint beginning in version 16.04.125

Example Call

http://localhost:8181/Cart/GetShipTo?SiteID=1

Example Response - Success

{

"GetShipToResult": {

"error": {},

"response": {

"Cart.GetShipTo": {

"Success": true,

"ShipTo": {

"sh_id": 1578,

"sh_name": "4 STATE SUPPLY",

"sh_contact": Bill Smith

"sh_active": true,

"sh_addressvalid": null,

"sh_availall": false,

"sh_brid": 1,

"sh_city": "LENEXA",

"sh_country": "US",

"sh_county": "",

"sh_dba": "4 WAY SHEET",

"sh_email": "[email protected]",

"sh_exempt": true,

"sh_exemptexpires": null,

"sh_fax": "",

"sh_notes": "",

"sh_phext": "",

"sh_phone": "913-894-9484",

"sh_quota": 0.0,

"sh_s1id": 23,

"sh_s2id": 18,

"sh_s3id": 1,

"sh_s4id": 1,

"sh_s5id": 2,

"sh_smid": 18,

"sh_state": "KS",

"sh_street": "14305 W 105TH ST",

"sh_street2": "",

"sh_street3": "",

"sh_trid": 1,

"sh_ttid": 0,

"sh_waid": 1,

"sh_webname": "",

"sh_zip": "66215-2048"

}

}

}

}

}

Looking up eCommerce Categories - /Item/GetEcommerceCategories

This function returns all eCommerce Categories linked to any Product Categories defined through Tools > Tools Maintenance > eCommerce Sites, based on the parameters specified. If no parameters are specified, all eCommerce Categories will be returned.

Parameters:

  • PartID (optional) -- a specific part ID to get an ecommerce category for
  • PartNumber (optional) -- a specific part number to get an ecommerce category for
  • CategoryID (optional) -- a Deacom category ID to get an ecommerce category for
  • Category (optional) -- a Deacom category name to get an ecommerce category for
  • SubCategoryID (optional) -- a Deacom subcategory ID to get an ecommerce category for
  • SubCategory (optional) -- a Deacom subcategory name to get an ecommerce category for
  • Images (optional) -- a Deacom image to get an ecommerce category for

Example Call (using Images as a parameter)

http://localhost:8181/item/GetEcommerceCategories?CategoryID=64&Images=true

Example Call (using PartID as a parameter)

http://localhost:8080/Item/GetEcommerceCategories?PartID=3700

Example Response - Success

{

"GetEcommerceCategoriesResult": {

"error": {},

"response": {

"Item.GetEcommerceCategories": {

"Categories": [{

"cc_id": 2,

"cc_ecomcat": "Category 2",

"cc_active": true,

"cc_default": false

}]

}

}

}

}

Example Response - Failure

{

"GetEcommerceCategoriesResult": {

"error": {},

"response": {

"Item.GetEcommerceCategories": {

"Error": "Could not find any categories for the given criteria."

}

}

}

}

Looking up item master data and on hand quantities - /Item/GetItems

This function returns item master data and on hand quantity limits for any parts meeting the above criteria. A few things worth noting:

  • The parts gathered must be part of the Product Categories grid on Tools > Tools Maintenance > Ecommerce Sites and are linked to Saleable Parts. For example, if you set up a Saleable Part for category 'Candy' with an on hand quantity of 100, then set up a Product Category record where the '8oz Chocolate' item belongs to main app category of Candy, you could make a call to this function using the ecommerce category ID that this chocolate item belongs to in order to get that on hand quantity of 100.
  • Only a single parameter should be specified in this function (i.e. only one of the following: part, category, sub-category, ecommerce category).
  • Included in the return of this function is the "OnHandEcommerceInventory" field, which displays the quantity on hand for this product within facilities with the "Include in eCommerce Inventory" flag set to true.

Paramaters

  • PartID (optional) -- a specific part ID to get item data for
  • PartNumber (optional) -- a specific part number to get item data for
  • CategoryID (optional) -- a Deacom category ID to get item data for
  • Category (optional) -- a Deacom category name to get item data for
  • SubCategoryID (optional) -- a Deacom subcategory ID to get item data for
  • SubCategory (optional) -- a Deacom subcategory name to get item data for
  • EcommerceCategoryID (optional) -- the specific ecommerce category ID
  • EcommerceCategory (optional) -- the specific ecommerce category name
  • EcommercePartID (optional) -- the ID of the specified Ecommerce Part
  • EcommercePart (optional) -- the Ecommerce Part name
  • Notes: 1. If the Ecommerce Part ID or Ecommerce Part parameter is provided, the logic finds the dmecommprod record (eCommerce Product) associated with it and returns all dxcmsprod records (Saleable Parts) linked to it. 2. This call contains a method - GetInventoryData - which returns an object containing the following information:
  • OutOfStock: boolean - controls whether the product is able to be sold
  • OnhandEcommerceInventory: decimal - the amount of inventory that is available to sell
  • BackorderInventory: decimal - the amount of backorder inventory remaining to be sold

Example Calls (using PartID and EcommercePart parameters)

http://localhost:8080/Item/GetItems?PartID=17291

http://localhost:8181/Item/GetItems?EcommercePart=Test

Example Response - Success

{

"GetItemsResult": {

"error": {},

"response": {

"Item.GetItems": {

"Items": [

{

"pr_id": 17291,

"pr_codenum": "Spice-Product JG 12",

"pr_descrip": "Spice-Product JG 12",

"pr_caid": 227,

"pr_c2id": 0,

"pr_lispric": 9.99,

"pr_salunid": 1,

"pr_unid": 1,

"pr_prunid": 1,

"pr_active": true,

"pr_custreq": false,

"pr_salable": true,

"ca_name": null,

"c2_name": null,

"SalesUnit": null,

"SalesFactor": 0.0,

"StockUnit": null,

"pr_details": null,

"pr_notes": "",

"pr_picture": 278,

"specimage": null,

"pr_user1": null,

"InventoryData": {

"OutOfStock": false,

"OnhandEcommerceInventory": 325.0,

"BackorderInventory": 0.0

},

"ImageIDs": "0"

}

],

"ItemData": {

"ItemCount": 1

}

}

}

}

}

Example Response - Failure

{

"GetItemsResult": {

"error": {},

"response": {

"Item.GetItems": {

"Error": "Only a single parameter should be specified. Please include only a single parameter (Part, Category, Subcategory, eCommerce Category, etc) in your call."

}

}

}

}

Potential failure scenarios:

  • Multiple parameters are specified.
  • No eCommerce Categories could be found for the given criteria.
  • No saleable parts could be found for the given product categories.
  • Getting eCommerce Parts - /Item/GetEcommerceParts
  • When called, this function returns data related to the ecommerce part (dmecommpart) and all saleable parts belonging to it (dxcmsprod).

Notes:

  • If the "Active" checkbox on the Edit eCommerce Product form is unchecked, that item and all of its product variants will not appear in the results for this API call. Functionally, this prevents the user from seeing the product at all on the website.
  • Price range filters in "Item/GetEcommerceParts" are now respected if there is a Deal that alters the price of the returned products.
  • Search results in the eCommerce site include results where the query matches a CMS Product category's name (partially or in full). CMSCategory elements are checked by name, then CMSCatLink elements are checked for any matching category links, then all saleable parts in those links are gathered, then those are referenced to check for CMSProds that match. The matches are added to the results.
  • Beginning in version 16.02.113, the /Item/GetEcommerceParts call will only calculate price (when a subsequent call is made to Item/GetData) if you are sorting by price.
  • Beginning in version 16.04.125, this endpoint returns a "TotalNumberOfSaleableParts" node. This node contains the total number of Saleable Part variants nested inside all of the returned top-level eCommerce parent products.
  • Beginning in version 16.04.126, new types of product sorting are now possible. This includes alphabetical order, best selling, and price (with the ability to specify a price range if desired).
  • Beginning in version 17.01.081, the "InventoryData" node from the Item/GetData endpoint is now also present the return for this Item/GetEcommerceParts endpoint. The "InventoryData" node returns details for a specific item.

Parameters

  • EcommercePartID (optional) -- The ecommerce part ID (ep_id)
  • EcommercePart (optional) -- The ecommerce part name (ep_name)
  • PartID (optional) -- The part ID (pr_id)
  • PartNumber (optional) -- The part number (pr_codenum)
  • CategoryID (optional) -- The category ID (ca_id)
  • Category (optional) -- The category name (ca_name)
  • SubCategoryID (optional) -- The subcategory (c2_id)
  • SubCategory (optional) -- The subcategory name (c2_name)
  • SortByBestSeller (optional) -- Boolean to return results sorted by amount shipped within 365 days
    • This parameter checks "or_qship" for its results.
  • SaleablePartsOnly (optional) - Boolean parameter that will return paginated lists of only Saleable Parts.
  • PriceRangeLow (optional) - Integer. Defines the lowest product price that will be used to filter products in the API call. Note: the SortByPrice option must be set to true in order to use this parameter.
  • PriceRangeHigh (optional) - Integer. Defines the highest product price that will be used to filter products in the API call. Note: the SortByPrice option must be set to true in order to use this parameter.
  • UnitName (optional) - This parameter will filter the returned product list to only those products whose "pr_unid" corresponds to a Unit with the specified name.
  • EcommerceCategoryIDs
  • EcommerceParentCategoryIDs

The two parameters above are used to submit a comma-delimited list of integers that correspond to CMSCategoryLink "cl_ccid" or "cl_parentccid" values. (This is performed as an AND search, so a product must satisfy all of the ID's that were submitted in order to be returned).

Example Call

http://localhost:8181/Item/GetEcommerceParts?EcommercePart=Test

Example Response - Success

{

"GetEcommercePartsResult": {

"error": {},

"response": {

"Item.GetEcommerceParts": {

"EcommerceParts": [

{

"ep_id": 9,

"ep_name": "Test",

"ep_descrip": "Test",

"SaleableParts": [

{

"CategoryID": 1,

"CategoryName": "Other",

"SubCategoryID": 1,

"SubCategoryName": "Test",

"PartID": 0,

"PartName": "",

"EcommercePartID": 9

},

{

"CategoryID": 100129,

"CategoryName": "Beer Test",

"SubCategoryID": 0,

"SubCategoryName": "",

"PartID": 6609,

"PartName": "BSLAGER",

"EcommercePartID": 9

}

]

}

]

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of the system not being able to find any eCommerce Parts for the given criteria.

{

"GetEcommercePartsResult": {

"error": {},

"response": {

"Item.GetEcommerceParts": {

"Error": "Could not find any eCommerce Parts for the given criteria."

}

}

}

}

Searching Item Headers - /Item/ItemSearchHeader

This API call is used for a searchbar with on the fly results in either a popout or dropdown style.

Parameters

  • SearchText (required)- Text you want to search the eCommerceParts for
  • NumberOfHeaderItems (optional) - Indicates the number of items, from the top of the list, to return. Default Value 4
  • UserFieldValues (optional) - a lookup of user field name (ex: u_ecomm_number) and value (ex: 8). This field is represented as a string with comma-delimited keys and values like so: [{"u_test_ecommprod_char":"test3"},{"u_test_ecommprod_numeric":"8"}]
  • SaleablePartsOnly (optional) - Boolean parameter that will return paginated lists of only Saleable Parts.
  • PriceRangeLow (optional) - Integer. Defines the lowest product price that will be used to filter products in the API call.
  • PriceRangeHigh (optional) - Integer. Defines the highest product price that will be used to filter products in the API call.

Notes:

  • If the "Active" checkbox on the Edit eCommerce Product form is unchecked, that item and all of its product variants will not appear in the results for this API call. Functionally, this prevents the user from seeing the product at all on the website.
  • When the UserFieldValues field is specified, the search results will be further filtered on the eCommerce Product user fields you specify. For example, using the above parameter will only return parts where u_test_ecommprod_char = 'test3' and u_test_ecommprod_numeric = 8. Not that due to the nature of these two functions, the way that the UserFieldValues parameter is handled varies; the ItemSearch function treats the UDF values as an AND statement which will further filter the results, while the ItemSearchHeader function adds the filter as an OR, pulling in additional records that meet the UDF criteria.

Example Calls

http://localhost:8181/Item/ItemSearchHeader?SearchText=Duck

http://localhost:8181/Item/ItemSearchHeader?UserFieldValues=[{"u_test_ecommprod_char":"test3"}]

Example Response - Success

{

"ItemSearchHeaderResult": {

"error": {},

"response": {

"TotalNumberOfRecords" : 3

"UserFields": {},

"EcommerceParts": [

{

"ep_id": 15,

"ep_name": "Duck",

"ep_descrip": "smallest of the waterfoul family",

"SaleableParts": [

{

"CategoryID": 100126,

"CategoryName": "",

"SubCategoryID": 18,

"SubCategoryName": "Duck",

"PartID": 5519,

"PartName": "",

"EcommercePartID": 15

},

{

"CategoryID": 100126,

"CategoryName": "",

"SubCategoryID": 18,

"SubCategoryName": "Duck",

"PartID": 5519,

"PartName": "",

"EcommercePartID": 15

}

]

},

{

"ep_id": 16,

"ep_name": "FINI1",

"ep_descrip": "Finished good1-No BFz2sds",

"SaleableParts": [

{

"CategoryID": 100126,

"CategoryName": "",

"SubCategoryID": 18,

"SubCategoryName": "Duck",

"PartID": 3700,

"PartName": "",

"EcommercePartID": 16

}

]

},

{

"ep_id": 19,

"ep_name": "Mallard",

"ep_descrip": "Nulla mollis tristique aliquam",

"SaleableParts": [

{

"CategoryID": 100133,

"CategoryName": "",

"SubCategoryID": 26,

"SubCategoryName": "Ducks",

"PartID": 7822,

"PartName": "",

"EcommercePartID": 19

},

{

"CategoryID": 100133,

"CategoryName": "",

"SubCategoryID": 26,

"SubCategoryName": "Ducks",

"PartID": 7823,

"PartName": "",

"EcommercePartID": 19

},

{

"CategoryID": 100133,

"CategoryName": "",

"SubCategoryID": 26,

"SubCategoryName": "Ducks",

"PartID": 7821,

"PartName": "",

"EcommercePartID": 19

}

]

}

]

}

}

}

Example Response - Failure

Not applicable to the search API. If no records are found the system will indicate 0 records found.

Searching Items - /Item/ItemSearch

This API call is used for your pagination functionality; however the user chooses to do it, infinite or paged.

Parameters

  • SearchText (optional) - Text you want to search the eCommerceParts for
  • PageNumber (required) - The Page you are requesting products for
  • NumberOfItemsPerPage (required) - Number of items you will have per-page
  • UserFieldValues (optional) - a lookup of user field name (ex: u_ecomm_number) and value (ex: 8). This field is represented as a string with comma-delimited keys and values like so: [{"u_test_ecommprod_char":"test3"},{"u_test_ecommprod_numeric":"8"}]
  • TagText (optional) - allows for User Defined Fields to be searched in one single API call over 5. This allows a UserFieldValues search across a set of User Fields instead of just a single User Field and retains the filtering of User Fields as on OR, so that the search will return all products that match at least one of the User Field filters. An example of a call using this option is listed in the "Example Calls" section below.
  • SortByBestSeller (optional) -- Boolean to return results sorted by amount shipped within 365 days
    • This parameter checks "or_qship" for its results.
  • SaleablePartsOnly (optional) - Boolean parameter that will return paginated lists of only Saleable Parts.
  • PriceRangeLow (optional) - Integer. Defines the lowest product price that will be used to filter products in the API call.
  • PriceRangeHigh (optional) - Integer. Defines the highest product price that will be used to filter products in the API call.

Version 17.01.059 adds the following four parameters to allow the ability to search by multiple categories:

  • CategoryID - selects all products with a matching cp_caid
  • SubCategoryID - selects all products with a matching cp_c2id
  • EcommerceCategoryIDs - This parameter and one below used to submit a comma-delimited list of integers that correspond to CMSCategoryLink "cl_ccid" or "cl_parentccid" values. (This is performed as an AND search, so a product must satisfy all of the ID's that were submitted in order to be returned).
  • EcommerceParentsCategoryIDs

Notes:

  • If the "Active" checkbox on the Edit eCommerce Product form is unchecked, that item and all of its product variants will not appear in the results for this API call. Functionally, this prevents the user from seeing the product at all on the website.
  • When the UserFieldValues field is specified, the search results will be further filtered on the eCommerce Product user fields you specify. For example, using the above parameter will only return parts where u_test_ecommprod_char = 'test3' and u_test_ecommprod_numeric = 8. Not that due to the nature of these two functions, the way that the UserFieldValues parameter is handled varies; the ItemSearch function treats the UDF values as an AND statement which will further filter the results, while the ItemSearchHeader function adds the filter as an OR, pulling in additional records that meet the UDF criteria.
  • Version 16.03.021 added the TagText parameter and made the SearchText parameter optional. SearchText was made optional so that searching could be done on User Fields alone.
  • Beginning in version 17.01.081, the "InventoryData" node from the Item/GetData endpoint is now also present the return for this Item/ItemSearch endpoint. The "InventoryData" node returns details for a specific item.

Example Calls

http://localhost:8181/Item/ItemSearch?SearchText=Duck&PageNumber=1&NumberOfItemsPerPage=2

http://localhost:8181/Item/ItemSearch?UserFieldValues=[{"u_test_ecommprod_char":"test3"}]

http://localhost:8181/Item/ItemSearch?TagText=Seasonal Cookies&PageNumber=1&NumberOfItemsPerPage=9&SiteID=3 *(This call will return all items that have a user field with a value of Seasonal Cookies in the first group of 9.)

Example Response - Success

{

"ItemSearchResult": {

"error": {},

"response": {

"TotalNumberOfRecords" : 3

"UserFields": {},

"EcommerceParts": [

{

"ep_id": 15,

"ep_name": "Duck",

"ep_descrip": "smallest of the waterfoul family",

"SaleableParts": [

{

"CategoryID": 100126,

"CategoryName": "",

"SubCategoryID": 18,

"SubCategoryName": "Duck",

"PartID": 5519,

"PartName": "",

"EcommercePartID": 15

},

{

"CategoryID": 100126,

"CategoryName": "",

"SubCategoryID": 18,

"SubCategoryName": "Duck",

"PartID": 5519,

"PartName": "",

"EcommercePartID": 15

}

]

},

{

"ep_id": 16,

"ep_name": "FINI1",

"ep_descrip": "Finished good1-No BFz2sds",

"SaleableParts": [

{

"CategoryID": 100126,

"CategoryName": "",

"SubCategoryID": 18,

"SubCategoryName": "Duck",

"PartID": 3700,

"PartName": "",

"EcommercePartID": 16

}

]

}

]

}

}

}

Note: The results are ranked based on what is entered as SearchText. If a number is detected and can be parsed out from the passed in string, this part will always be number one in the results. After that, it stacks up the same for if a part id is entered or not by searching name of the following: Part, Category, Sub Category.

Example Response - Failure

Not applicable to the search API. If no records are found the system will indicate 0 records found.

Looking up inventory levels - /Item/GetInventoryLevels

This API call is used to gather inventory levels for the appropriate part numbers.

Notes:

  • This API returns 1 result per part number based on instant MRP. Each JSON result returns all columns in instant MRP.
  • The end date is set to the current date that this API is being run on.
  • This API searches only within facilities where the "Include In eCommerce Inventory" (wa_ecomminv) flag is set to TRUE. The wa_ecomminv flag is located on the Sales tab of the Facility record.
  • Beginning in version 17.01.030, the automated MRP functions in eCommerce have been revamped to better mimic the main Deacom application. The following MRP filters have been implemented: safetydayscalc, salescalc, directstaging, qcleadttime, so_datebasedon, po_datebasedon, job_datebasedon, purchasescalc, jobscalc, icxferscalc, and leadtimecalc

Required Parameters

At least one of the following.

  • ItemNumbers - list of item ID's (pr_id)
  • Categories - list of Categorie ID's (pr_caid)
  • SubCategories - List of subcategories (pr_c2id)

Optional Parameters

These correlate to the options on the MRP report pre-filter.

  • ItemSearch1-5 - int (ID)
  • ItemPlanner - int (ID)
  • Source - char
  • ItemType - char
  • QuantityIn - char
  • QuantityNotIn - char
  • ReorderPoint - char
  • Suggestions - char
  • SuggestionsBefore - int
  • Inactivity - char
  • CreditHoldOrders - char
  • ForecastOrders - char
  • QC - char
  • QCAggregate - char
  • NetValue - char
  • Issued - char
  • Reserved - char
  • Expired - char
  • JobStatus - char
  • JobRequirements - char
  • IndirectJobReqs - char
  • IndirectRequirements - char
  • OverIssue - char

Example Call

http://localhost:8181/Item/GetInventoryLevels?RequiredParameters={"ItemNumbers":[5594]}

Example Response - Success

{

"GetInventoryLevelsResult": {

"error": {},

"response": {

"Item.GetInventoryLevels": {

"Success": {

"Records": 1,

"InventoryLevels": [

{

"PartNumber": "slraw1",

"PartInfo": "Selected",

"PartInfo2": "No",

"Value": "Suggested",

"Vendor": "",

"May 11": 497850.0,

"May 18": 0.0,

"May 25": 0.0,

"June 1": 0.0,

"June 8": 0.0,

"June 15": 0.0

}

]

}

}

}

}

}

Example Response - Failure

Not applicable to this API.

Return a breakdown of all available item discounts - /Item/GetPricingMatrix

This endpoint shows a breakdown of all available discounts for a given item at various quantities (Along with accompanying details about that discount).

Additionally, this endpoint is designed to show tiered pricing information for different quantities of items. It takes Pricing Orders, Deals, and Promotions into account to calculate this. Below is the order of priority when multiple price modifiers apply, with the top being the highest priority. Modifiers will override each other if a higher priority modifier exists. Promotions are the only exception to this rule. Promotions will always be considered, but they will be applied last, after all other modifiers are already applied.

  • Pricing Order (Ship To)
  • Pricing Order (Bill To)
  • Pricing Order (Billing Group)
  • Deal Pricing (Specific Bill To or Specific Ship To)
  • Deal Pricing (All Bill To’s or All Ship To’s)
  • Item Master List Price

Promotions

When the API returns JSON, the prices will be ordered with the lowest quantity ascending to the highest quantity. Typically, the more of the item that is ordered, the greater the discount. If a Deal, Pricing Order, or Promotion would be enabled at a certain quantity ordered, that potential price is added to the breakdown and shown as a pricing option in the returned JSON. These prices follow the usual Deacom pricing hierarchy.

NOTE: This endpoint is different than traditional endpoints in that no paramters are used in this call and the call will display a matrix of available pricing discounts.

Basic Deal Example:

Explations are available following the screenshot.

GetPricing1.png

If there is a Deal that has changed the price, the response will look like the example to the right.

The “Quantity_Threshold” is the number of units of the item that must be ordered to receive this discount.

The “Price_Per_Sales_Unit” is the cost for 1 atomic unit of the item at the desired quantity. (e.g., 1 pound).

The “Price_Per_Container” is the cost for 1 box of the item. If a box contains a mandatory bulk of items, this will differ from the “Price_Per_Sales_Unit”. This image shows an item where a box contains 25 pounds of the item. The price per sales unit is 5 dollars, but the “Sales_Unit_Factor” is 25, so 25 pounds are in this container.

The “Price_Extended” is the total cost of all containers of the item if it is ordered at the desired quantity.

The “Pricing_Source” is the reason for the discount. This can be a variety of Pricing Order types, a Deal, or a Promotion.

The “Deal_Info” node simply contains all of the information about the Deal that applied, if a Deal was the reason for the price.

Basic Promotion Example:

Explations are available following the screenshot.

GetPricing2.png

If a Promotion has changed the price, the response will look like this example. All properties are similar to the Deal example, except for the “Promo_Info” node, which serializes all the promotion’s properties.

An important note when a pricing source is listed as “Promotion”, the highest priority Pricing Order or Deal is considered. If a Deal went into effect at 10 units ordered, but a Promotion goes into effect at 12 units ordered, the previous Deal will carry over if 12 units were ordered.

Therefore, the price nodes in this response are up to date with any Deals/Pricing Orders that took effect at lower quantities ordered.

Multiple Discount Example:

Explations are available following the screenshot.

GetPricing3.png

If there are 2 discount sources that overlap, the prices will be serialized differently.

A Deal for 30% off exists if 20 items are ordered, and a promotion for 7% off exists if more than 12 items were ordered. If you order 20 containers of the item, these 2 discounts will stack.

If this happens, the “Base_Prices” node will reflect the Deal price. However, an additional node will exist only in this case, called “Best_Promo_Prices”. This will reflect the Deal price with the best qualifying promotion applied on top of it. (e.g., 30% off, with a further 7% off applied afterwards).

If more promotions existed that were valid for the item, the “Best_Promo_Prices” node would reflect the best one, which is the one the system will choose by default. This is the price that should be reflected for the user.

Obtain modified Item records - /Item/GetModifiedRecords

This API call will obtain information on modified records from the Item Master (dmprod) table for the specified time period. (Added in version 16.07.054)

Parameters

  • Site ID (required) - the ID of the eCommerce site.

Example Call

http://localhost:8181/Item/GetModifiedRecords?SiteID=1&StartDate=8/5/2021 23:59:59&EndDate=8/6/2021 17:00:00

Example Response - Success

The success response will be similar to the /General/GetModifiedRecords, but will only include information from the Item Master (dmprod) table.

Example Response - Failure

N/A - Users may receive some generic errors in the case of a failure.

Obtain information for new Item records - /Item/GetNewRecords

This API call will obtain information on new records added to the Item Master (dmprod) table for the specified time period. (Added in version 16.07.054)

Parameters

  • Site ID (required) - the ID of the eCommerce site.

Example Call

http://localhost:8181/Item/GetNewRecords?SiteID=1&StartDate=1/5/2022 23:59:59&EndDate=6/6/2022 17:00:00

Example Response - Success

The success response will be similar to the /General/GetNewRecords, but will only include information from the Item Master (dmprod) table.

Example Response - Failure

N/A - Users may receive some generic errors in the case of a failure.

Managing the cart contents

Once a cart is created, and generally after one or more parts have been added to it, the user may view the cart contents, update quantities of items in the cart, and delete items from the cart entirely.

Viewing details of an item - /Item/GetData

When a user needs more details for a given item, this call can be used to return information relative to the desired part. Note: All parameters are optional so if none are passed in, info for all parts will be returned.

This call will enforce the "Bill-To/Ship-To Cross Ref Required For Sales" flag on the DEACOM item master record. If a user selects an item with this flag checked, the system will verify that a customer part cross reference exists for the customer logged into the eCommerce site and the selected item. If a match is not found an error will be returned and the call will not be applied. Companies may need to code their front end to display the appropriate message in this situation.

Parameters

  • PartID (optional) -- the part ID
  • PartNumber (optional) -- the part number
  • CategoryID (optional) -- the category ID to filter on
  • Category (optional) -- the category name to filter on
  • SubCategoryID (optional) -- the sub-category ID to filter on
  • SubCategory (optional) -- the sub-category name to filter on
  • EcommercePartID (optional) -- the ID of the specified Ecommerce Part
  • EcommercePart (optional) -- the Ecommerce Part name
  • CalculatePrice (optional) - boolean - may be used by the front end to just calc the price for the first salable part and not worry about it for others

Notes:

  • If the Ecommerce Part ID or Ecommerce Part parameter is provided, the logic finds the dmecommprod record (eCommerce Product) associated with it and returns all dxcmsprod records (Saleable Parts) linked to it. 2. This call contains a method - GetInventoryData - which returns an object containing the following information:
  • OutOfStock: boolean - controls whether the product is able to be sold
  • OnhandEcommerceInventory: decimal - the amount of inventory that is available to sell
  • BackorderInventory: decimal - the amount of backorder inventory remaining to be sold
  • The "pr_incsale" property is added to the returned JSON beginning in 17.01.098.

Example Calls

http://localhost:8080/Item/GetData?PartID=3700

http://localhost:8181/Item/GetData?EcommercePart=Test

http://localhost:5051/Item/GetData?PartID=17291&SiteID=1

Example Response - Success

The below is an example of a successful call response using the http://localhost:5051/Item/GetData?PartID=17291&SiteID=1 call

{

"GetDataResult": {

"error": {},

"response": {

"Item.GetData": {

"UserFields": {

"17291": {}

},

"Items": [

{

"pr_id": 17291,

"pr_codenum": "Spice-Product 12 pack",

"pr_descrip": "Spice-Product 12 pack",

"pr_caid": 227,

"pr_c2id": 0,

"pr_lispric": 9.99,

"pr_minsale": 2.00,

"pr_incsale": 0,

"pr_salunid": 1,

"pr_unid": 1,

"pr_prunid": 1,

"pr_active": true,

"pr_custreq": false,

"pr_salable": true,

"ca_name": "eCommerce",

"c2_name": "",

"SalesUnit": "Each",

"SalesFactor": 1.0,

"StockUnit": "Each",

"pr_details": "",

"pr_notes": "",

"pr_picture": 278,

"specimage": "",

"pr_user1": "",

"InventoryData": {

"OutOfStock": false,

"OnhandEcommerceInventory": 325.0,

"BackorderInventory": 0.0

},

"ImageIDs": "0"

}

]

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of the system not being able to find any parts for the given criteria.

{

"GetDataResult": {

"error": {},

"response": {

"Item.GetData": {

"Error": "Could not find any parts for the given criteria."

}

}

}

}

Viewing details of Payment Types - /General/GetPaymentTypes

This call will be used to return information for the specified payment type. If no PaymentTypeID is specified, information will be returned for all active records.

Parameters

  • PaymentTypeID - the Payment Type ID from DEACOM

Example Call

http://localhost:8080/General/GetPaymentTypes

Example Response - Success

The below is an example of a successful call response.

{

"GetPaymentTypesResult": {

"error": {},

"response": {

"General.GetPaymentTypes": {

"PaymentTypes": [{

"c3_id": 7,

"c3_name": "American Express",

"c3_default": false,

"c3_active": true,

"c3_recon": false,

"c3_badchk": false,

"c3_chid": 246,

"c3_cashback": false,

"c3_recchid": 0,

"c3_recgain": 0,

"c3_ccmask": "9999-999999-99999",

"c3_creditcard": true,

"c3_giftcard": false,

"c3_max": 0,

"c3_cashchid": 0,

"c3_showcashreg": false,

"c3_seq": 7

}]

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid Payment Type ID.

{

"GetDataResult": {

"error": {},

"response": {

"General.GetPaymentTypes": {

"Error": "Payment Type information could not be found."

}

}

}

}

Viewing details of Terms - /General/GetTerms

This call will be used to return information for the specified term. If no TermID is specified, information will be returned for all active records.

Parameters

  • TermID(optional) - The ID of the Terms record in the dmterm table in DEACOM.

Example Call

http://localhost:8181/General/GetTerms

Example Response - Success

{

"GetTermsResult": {

"error": {},

"response": {

"General.GetTerms": {

"Terms": [

{

"ID": 2,

"Name": "COD",

"Notes": "Cash, cashier's check or credit card only.",

"RequireAuth": false,

"BillType": "Invoice",

"CCProcess": "None",

"PaymentDueDays": 0.0,

"PaymentDueType": "Number of Days"

},

{

"ID": 4,

"Name": "Net 30 Days",

"Notes": "",

"RequireAuth": false,

"BillType": "Invoice",

"CCProcess": "None",

"PaymentDueDays": 30.0,

"PaymentDueType": "Number of Days"

},

{

"ID": 23,

"Name": "6 Month Payoff",

"Notes": "",

"RequireAuth": false,

"BillType": "Invoice",

"CCProcess": "None",

"PaymentDueDays": 17.0,

"PaymentDueType": "Day of Month"

},

{

"ID": 25,

"Name": "12 Month Payoff",

"Notes": "",

"RequireAuth": false,

"BillType": "Invoice",

"CCProcess": "None",

"PaymentDueDays": 15.0,

"PaymentDueType": "Day of Month"

},

{

"ID": 29,

"Name": "10% Credit Card Prepay",

"Notes": "",

"RequireAuth": false,

"BillType": "Invoice",

"CCProcess": "With Authorization",

"PaymentDueDays": 0.0,

"PaymentDueType": "Number of Days"

}

{

"ID": 32,

"Name": "31st Pay 15th",

"Notes": "",

"RequireAuth": false,

"BillType": "Statement",

"CCProcess": "None",

"PaymentDueDays": 15.0,

"PaymentDueType": "Day of Month"

},

{

"ID": 34,

"Name": "Credit Card w Auth",

"Notes": "",

"RequireAuth": false,

"BillType": "Invoice",

"CCProcess": "With Authorization",

"PaymentDueDays": 0.0,

"PaymentDueType": "Number of Days"

},

{

"ID": 45,

"Name": "Credit Card without Authorization",

"Notes": "",

"RequireAuth": false,

"BillType": "Invoice",

"CCProcess": "Without Authorization",

"PaymentDueDays": 0.0,

"PaymentDueType": "Number of Days"

},

{

"ID": 46,

"Name": "Zero Dollar Authorization",

"Notes": "",

"RequireAuth": false,

"BillType": "Invoice",

"CCProcess": "Zero Dollar Authorization",

"PaymentDueDays": 0.0,

"PaymentDueType": "Number of Days"

},

{

"ID": 49,

"Name": "Credit Card 50% w Auth",

"Notes": "",

"RequireAuth": false,

"BillType": "Invoice",

"CCProcess": "With Authorization",

"PaymentDueDays": 0.0,

"PaymentDueType": "Number of Days"

}

]

}

}

}

}

Example Response - Failure

{

"GetTermsResult": {

"error": {},

"response": {

"General.GetTerms": {

"Error": "Could not find any active Terms for the given criteria."

}

}

}

}

Viewing details of shipping costs - /Cart/GetShippingCosts

This call is used to return all possible shipping costs for the current order, generated from EasyPost or UPS\FedEx. When the call is processed, the system will return a list of all active Ship Via Methods and gather the shipping costs based on the current cart data assigned to the user's session through EasyPost or UPS\FedEx. The returned data will display the Ship Via Method and the rate associated. If the ShipMethods parameter is passed into this call, the system will only return the rate for the specific Ship Via Methods that are passed into the call.

Parameters

  • ShipMethods(optional) - a comma-delimited list of ship via IDs (tr_ids) to filter on.
  • EasyPost(optional) - boolean. Defaults to True. When set to True, shipping rates, of the ship via IDs passed in, are generated via EasyPost. When set to False, shipping rates, of the ship via IDs passed in, are generated via FedEx or UPS (depending on the setting in dmtruk.tr_svctype) Notes: 1. When this parameter is set to False, the optional parameter of ShipMethods must be provided. If ShipMethods parameter is not specified or does not match the applicable Ship Via Methods, the response returned by Cart/Shipping Costs will be blank. 2. Beginning in version 16.04.084, the "Use EasyPost For Shipping Rates" flag, on the eCommerce Site form, can be used to have EasyPost calculate shipping rates in the eCommerce application. The system will check to see if this flag or the EasyPost parameter is set when determining if EasyPost should be used to calculate shipping rates

Notes: Regarding setup and restrictions.1.Shipping costs assume that all contents of a cart/order will be made with a single package. 2. The package weight is calculated in the base weight unit. If no base weight unit is declared, the functionality assumes LBs. 3. In situations when UPS and FedEx services go down, a 'Message' property has been added to the response for this call, which will only ever be filled in when an error is returned by the services. 4. FedEx returns the estimated delivery days as a character, not as a string. For example, "SIX_DAYS" rather than "6" like UPS does. Note that this value is also the Maximum Delivery Days value, since no other property returns the estimated delivery day count.

Example Calls

The first example call is with the EasyPost parameter set to True. The second example call is with the EasyPost parameter set to False.

http://localhost:8181/Cart/GetShippingCosts?SiteID=3&EasyPost=true&ShipMethods=12,14,80

http://localhost:8181/Cart/GetShippingCosts?SiteID=3&EasyPost=false&ShipMethods=72, 71, 76, 80

Example Responses - Success

The first example success response is when the EasyPost parameter is set to True. The second example success response is when the EasyPost parameter is set to False.

Example Response - Success (with EasyPost parameter set to True)

{

"GetShippingCostsResult": {

"error": {},

"response": {

"Cart.GetShippingCosts": {

"ShippingCosts": [

{

"tr_id": 14,

"Carrier": "FedEx",

"Service": "FEDEX_GROUND",

"Currency": "USD",

"Rate": "$8.40",

"DeliveryDays": 1,

"DeliveryDate": "Unknown"

},

{

"tr_id": 80,

"Carrier": "FedEx",

"Service": "FEDEX_EXPRESS_SAVER",

"Currency": "USD",

"Rate": "$17.19",

"DeliveryDays": 5,

"DeliveryDate": "12/09/2019"

},

{

"tr_id": 12,

"Carrier": "FedEx",

"Service": "FEDEX_2_DAY",

"Currency": "USD",

"Rate": "$19.50",

"DeliveryDays": 2,

"DeliveryDate": "12/06/2019"

}

]

}

}

}

}

Example Response - Success (with EasyPost parameter set to False)

{

"GetShippingCostsResult": {

"error": {},

"response": {

"Cart.GetShippingCosts": {

"ShippingCosts": [

{

"tr_id": 72,

"Service": "3 Day Select",

"Carrier": "UPS",

"DeliveryDays": "3",

"Rate": 21.12,

"Currency": "USD",

"Message": null

},

{

"tr_id": 71,

"Service": "Next Day Air",

"Carrier": "UPS",

"DeliveryDays": "1",

"Rate": 89.8,

"Currency": "USD",

"Message": null

},

{

"tr_id": 76,

"Service": "STANDARD_OVERNIGHT",

"Carrier": "FedEx",

"DeliveryDays": "EIGHTEEN_DAYS",

"Rate": 82.7,

"Currency": "USD",

"Message": null

},

{

"tr_id": 80,

"Service": "FEDEX_EXPRESS_SAVER",

"Carrier": "FedEx",

"DeliveryDays": "EIGHTEEN_DAYS",

"Rate": 25.14,

"Currency": "USD",

"Message": null

}

]

}

}

}

}

Example Response - Failure

N/A - Users may receive some generic errors in cases where a cart does not exist etc., but there are no specific error messages associated with this call.

Viewing the contents of a cart - /Cart/GetCartItems

Once one or more parts have been added to a cart, this call will be used to retrieve and display the contents.

Note: In eCommerce, the "Cart/GetCartItems" endpoint has been enhanced with a new node in the returned JSON called "PromotionalDiscount". This node contains the total discounted price off of the eCommerce order if any promotions are applied. This node is intertwined with the "Subtotal" and "ShippingCosts" nodes, with each providing totals for different kinds of items in the cart. These nodes can be directly used by the front-end to summarize the cart costs. These 3 nodes (Promotional Discount, Subtotal, Shipping Costs). provide the 3 essential breakdowns of the pricing of the cart. This can be used on the front-end sites to get very accurate information about the way the cart is priced. Additionally, fail-safes have been put in place to ensure that promotional costs are reported correctly in the cart after running a retotal within the Deacom pricing hierarchy. Promotional costing should be very accurately reported now.

Optional Parameters

  • FreeShippingPromo- If the user has a free shipping promo item ID in the cart, all shipping costs are removed automatically.

Version Notes:

  • Beginning in version 16.04.112 (and higher), the following Cart Item fields have been removed: "IsCalcItem", "IsManualTaxItem", and "IsFreightOrShippingItem". They have been replaced with a new string property called "ItemClassification". This is an enum which can contain the following values, which are automatically selected based on the item's type: "Product", "Promotion", "Shipping", "Tax", and "UserCalculation". This change enables the front-end developers to read a consistent node which describes how the item should behave. The "Cart/GetCartItems" JSON has also been cleaned up.
  • Beginning in version 16.04.125, this endpoint now reports the name of the Sales Unit for each of the returned cart items.
  • Beginning in version 16.07.110, the following fields have been added to this endpoint: "pm_minimum", "pm_minimumtype", "pm_on", and "pm_onnum". This allows the cart to interface with the eCommerce front end, so that a warning can be displayed if the user is about remove enough units of an item from the cart to disqualify them for a promotion.
  • Beginning in version 17.02.014, the following fields have been added and are available to be returned in this endpoint to support the ability to preview user calc discounts during checkout: to_s2id, pr_user7, or_salunid

Example Call

http://localhost:8080/Cart/GetCartItems

Example Response - Success

The below is an example of a successful call response.

{

"GetCartItemsResult": {

"error": {},

"response": {

"Cart.GetCartItems": {

"Success": {

"ep_name": "Clothing",

"ep_descrip": "Clothing Items",

"ca_id": 2209,

"ca_date": "10/3/2019 4:41:38 PM",

"ca_uaid": 2028,

"ca_numitem": 2,

"ca_total": 0.0,

"ca_current": true,

"ca_active": true,

"ca_shid": 2671,

"ca_ponum": "",

"ca_sessionid": "4043699458a34b99854f2473b6d4996f",

"ca_name": "",

"ca_brid": 0,

"ca_notes": "",

"ca_deliverydate": "10/03/2019",

"ca_weight": 0.0,

"ca_tax": 0.0,

"ca_biid": 2115,

"ca_trid": 12,

"CartItems": [

{

"ct_id": 2194,

"ct_caid": 2209,

"ct_prid": 5519,

"ct_ordquant": 1,

"ct_confirmnum": "",

"ct_pmid": 0,

"ct_price": 100.0,

"ct_shid": 0,

"ct_trid": 0,

"ct_frid": 0,

"pr_codenum": "Duck"

},

{

"ct_id": 2195,

"ct_caid": 2209,

"ct_prid": 7721,

"ct_ordquant": 1,

"ct_confirmnum": "",

"ct_pmid": 0,

"ct_price": 30.0,

"ct_shid": 0,

"ct_trid": 0,

"ct_frid": 0,

"pr_codenum": "Swan"

}

]

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid cart ID.

{

"GetCartItemsResult": {

"error": {},

"response": {

"Cart.GetCartItems": {

"Error": "Cart does not exist."

}

}

}

}

Updating the quantity of an item in a cart - /CartItem/Update

Once one or more parts have been added to a cart, this call will be used to update the quantity of an item in the cart. CartItemID and PartID are both optional, but at least one must be specified.

Notes:

  • The ca_numitem field in this call tracks the total amount of items ordered.
  • Cart serialization works when receiving a JSON return from the "CartItem/Update" API endpoint.

Parameters

  • CartItemID - the Cart Item ID obtained from the ct_id value returned in the Cart.GetCartItems call
  • PartID - the Part ID from DEACOM
  • Optional Parameters
  • ShipToID -- the ID of the Ship-to to set on the cart item
  • ShipViaID -- the ID of the ship via method to set on the cart item
  • FreightID -- the ID of the freight to set on the cart item
  • Quantity - the new number of units of the part that should be in the cart
  • Notes - text field. Used to set sales order line notes (or_notes) after an item has already been added to the cart.

Note: At least one of the ShipToID, ShipViaID, FreightID, or Quantity parameters must be provided for a cart to be updated. Also, in the case of Master Orders, if an individual cart item is not updated using this call, the Ship-to, Ship Via, and Freight will all default from the cart.

Example Call

If the CartItemID is being used, use http://localhost:8080/CartItem/Update?CartItemID=YYYY&Quantity=Z

If the PartID is being used, use http://localhost:8080/CartItem/Update?PartID=YYYY&Quantity=Z

Example Response - Success

The below is an example of a successful call response.

{

"UpdateResult": {

"error": {},

"response": {

"CartItem.Update": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid Cart Item ID.

{

"UpdateResult": {

"error": {},

"response": {

"CartItem.Update": {

"Error": "Cart item does not exist."

}

}

}

}

Deleting an item from a cart - /CartItem/Delete

Once one or more parts have been added to a cart, this call will be used to remove an item (or a Child Order, if Master Orders are being used). CartItemID and PartID are both optional, but at least one one must be specified.

Note: The ca_numitem field in this call tracks the total amount of items ordered.

Parameters

  • CartItemID - the Cart Item ID obtained from the ct_id value returned in the Cart.GetCartItems call
  • PartID - the Part ID from DEACOM
  • ShipToID(optional) - Items sharing the same Part ID can now be deleted from the cart based on their associated Ship-To. This removes the necessity for all items with the same Part ID to be deleted if it is desired that only those items belonging to one Ship-To are deleted.

Example Call

If the Cart Item ID is being used, use http://localhost:8080/CartItem/Delete?CartItemID=YYYY

If the Part ID is being used, use http://localhost:8080/CartItem/Delete?PartID=YYYY

Example Response - Success

The below is an example of a successful call response.

{

"DeleteResult": {

"error": {},

"response": {

"CartItem.Delete": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of not specifying the Cart Item ID or Part ID.

{

"DeleteResult": {

"error": {},

"response": {

"CartItem.Delete": {

"Error": "You must enter a cart item id or a part id."

}

}

}

}

Deleting all contents from a cart - /Cart/Delete

Once one or more parts have been added to a cart, this call will be used to delete the cart entirely.

Parameters

  • KeepCart - Optional. A boolean parameter that defaults to False. When it is provided as true, the functionality will remove all contents from the cart but will retain the cart, rather than delete it, preventing the user from needing to call Cart/Create again to start the shopping process over again.

Example Call

http://localhost:8080/Cart/Delete

Example Response - Success

The below is an example of a successful call response.

{

"DeleteResult": {

"error": {},

"response": {

"Cart.Delete": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of an invalid cart.

{

"DeleteResult": {

"error": {},

"response": {

"Cart.Delete": {

"Error": "Cart does not exist"

}

}

}

}

Get item images from the specific IDs - /Item/GetImage

This API is used for gathering images from an item master. This function does not return the same JSON result as most other functions do. Instead, it returns the Base64 image based on the ID

Parameters

  • ImageID - the file name of the image

Example Call

http://localhost:8080/Item/GetImage?ImageID=2019

Example Response - Success

data:image/png;base64,

/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAAAAAAAP/sABFEdWNreQABAAQAA etc.

Example Response - Failure

{

"Item.GetImage": {

"Error": "An image with that name does not exist."

}

}

Get item images attached to Document Categories - /General/GetImages

This API returns all images attached to Document Categories specified on the eCommerce site for eCommerce Products, optionally filtered by Document Category Type.

Notes:

  • Images that are attached to Document Categories on the eCommerce site with a Document Type of "Carousel" will not be displayed if the items these images are attached to are restricted by a Restricted Selling Group on the Ship-To record assigned to the eCommerce user.
  • Later versions of Deacom add better support for image scaling when using a Document Type of "Carousel" on eCommerce Document Categories. Additional information is available via Recommended eCommerce Image Sizes.

Parameters

  • SiteID - The SiteID indicates the ID number for the site. The Site ID can be obtained from the "cs_id" field on the cmssite grid.
  • DocumentCategoryType - The "ed_type" assigned to the Document Category on the eCommerce site.

Example Call

http://localhost:8180/General/GetImages?SiteID=2&DocumentCategoryType=Carousel

Example Response - Success

{

"GetImagesResult": {

"error": {},

"response": {

"General.GetImages": {

"Images": [

{

"ID": 51,

"Source": "/img/items/90/Test.png",

"RedirectURL": ""

},

{

"ID": 52,

"Source": "/img/items/96/Test.png",

"RedirectURL": ""

},

{

"ID": 53,

"Source": "/img/items/326/Spices.png",

"RedirectURL": ""

}

]

}

}

}

}

Example Response - Success

N/A - The call will not return any results if none are found that match the parameters.

Get documents attached to sales orders - /User/GetOrderDocs

This API takes the order number and returns any documents, including images, attached to the sales order. The call returns: Document Name (Name of document), Description (Description of document), Picture: (Base64 formatted picture), and Archived (If the image has been archived or not)

Parameters

  • OrderNumber - (required) the sales order number to check for attached documents.

Example Call

http://localhost:8181/User/GetOrderDocs?OrderNumber=2020-13974-00

Example Response - Success

"GetOrderDocsResult": {

"error": {},

"response": {

"User.GetOrderDocs": {

"Document": {

"Name": "confirmation_1.pdf",

"Description": "Confirmation",

"Picture":<Base64 Image>

"Archived": true

}

}

}

}

}

Example Response - Failure

None. The call will not return any results if an attached document(s) is not found.

Set Order User Fields - /Cart/SetHeaderUDFs

This call will set any sales order userfields on the order header during sales order creation. Specifically, after the /Cart/SetHeaderUDFs call has been used, the Checkout() method will propagate any custom-set User Fields to the resulting Sales Order Header.

Required Parameters

  • SOHeaderUDFs - (default: empty string) The input to this will look the same as it does to General.SetUserFieldValues and the system should parse this input and add it into the CartModel.SOHeaderUDFs if there is input. The call will be sure to check if the input is valid for a SO Header UDF

Example Call

http://localhost:8181/Cart/SetHeaderUDFs?SiteID=1&SOHeaderUDFs=[{%2710%27:%27150%27}]

Example Response - Success

"SetHeaderUDFsResult": {

"error": {},

"response": {

"Cart.SetHeaderUDFs"{

"Success": true,

"Result": ["SUCCEEDED setting UDF: [TYPE: Numeric] - [ID: 10] - [NAME: u_Actual_Weight] - [VALUE: 199]","SUCCEEDED setting UDF: [TYPE: Date]

- [ID: 1098] - [NAME: u_Order_Event_Date] - [VALUE: 4/30/2021]"

]

}

}

}

}

}

Example Response - Failure

"SetHeaderUDFsResult": {

"error": {},

"response": {

"Cart.SetHeaderUDFs": {

"Error": "Argument Error - One or more of the desired UDFs failed to apply. Please check the Result

node for details.",

"Result": ["FAILED setting UDF: [ID: 109] - [ERROR: Could not find a user field with this ID.]","SUCCEEDED setting UDF: [TYPE: Date] - [ID: 1098] - [NAME: u_Order_Event_Date] - [VALUE:

4/30/2021]"

]

}

}

}

}

Set valid fields, including userfields, on a cart - /Cart/Update

This call can be used to set or update any valid field for items and orders in the cart, including user calcualtion and user fields.

Required Parameters

  • NewValues - (default: empty string) - Notes - when the value is not empty, set the ca_notes for the cart

Example Call

http://localhost:8181/Cart/Update?SiteID=1&NewValues=[{'ca_active':'false'},{'ca_fail':'150'}]

Example Response - Success

"UpdateResult": {

"error": {},

"response": {

"Cart.Update": {

"Success": true,

"Result": "Update succeeded"

}

}

}

}

Eample Response - Failure

"UpdateResult": {

"error": {},

"response": {

"Cart.Update": {

"Error": "Failed to set field 'ca_fail'."

}

}

}

}

Assigning order information

Once a cart is created, a Bill-to Company, Ship-to Company, and PO Number can be assigned to the order in progress.

Assigning a Bill-to Company to the order - /Cart/SetBillToCompany

When called, this API sets the passed-in Bill-To ID to the cart linked to the current session. This is needed in cases where a person intends to check out without creating a user, but needs to provide Bill-to information to proceed.

Parameters

  • BillToID - (required) the Bill-to Company ID from DEACOM

Example Call

http://localhost:8181/Cart/SetBillToCompany?BillToID=2220

Example Response - Success

{

"Cart.SetBillToCompany":

{

"Success": true

}

}

Example Response - Failure

{

"SetBillToCompanyResult": {

"error": {},

"response": {

"Cart.SetBillToCompany": {

"Error": "Bill-To company is not valid."

}

}

}

}

Assigning a Ship-to Company to the order - /Cart/SetShipToCompany

Once a cart is created, this call will be used to assign a Ship-to Company to the order.

Parameters

  • ShipToID - the Ship-to Company ID from DEACOM

Example Call

http://localhost:8080/Cart/SetShipToCompany?ShipToID=YYYY

Example Response - Success

The below is an example of a successful call response.

{

"SetShipToCompanyResult": {

"error": {},

"response": {

"Cart.SetShipToCompany": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid Ship-to Company.

{

"SetShipToCompanyResult": {

"error": {},

"response": {

"Cart.SetShipToCompany": {

"Error": "Ship to company is not valid."

}

}

}

}

Assigning a PO Number to the order - /Cart/SetPONumber

Once a cart is created, this call will be used to assign a PO Number to the order.

Parameters

  • PONumber - represents the provided PO Number.

Example Call

http://localhost:8080/Cart/SetPONumber?PONumber=123456

Example Response - Success

The below is an example of a successful call response.

{

"SetPONumberResult": {

"error": {},

"response": {

"Cart.SetPONumber": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid Cart ID.

{

"SetPONumberResult": {

"error": {},

"response": {

"Cart.SetPONumber": {

"Error": "Cart does not exist."

}

}

}

}

Setting the Ship Via on the order - /Cart/SetShipVia

This call is used to set the correct ship via for the current cart.

Required Parameters:

  • SessionID - session ID to get the cart
  • ShipViaID (ca_trid) - the ship via ID

When a ship via ID is passed in, the system will set ca_trid to the value passed in for the cart specified in the session in the parameters.

Optional Parameters:

  • AddEasyPostFreight - boolean, defaults to false. When this is true, it will add the default freight part to the cart at the rate based on the passed in ShipViaID. Note that the rate for freight costs is generated by EasyPost using the rates returned from the Cart/GetShippingCosts function.
  • FreightCost - Sets the default freight part for the system to add to the backing Sales Order at the chosen price.
  • FreeShippingPromo- If the user has a free shipping promo item ID in the cart, all shipping costs are removed automatically.

Note: The default freight part will be synced down to the eCommerce database every time a sync is performed to ensure that it exists.

Example call:

http://localhost:8181/Cart/SetShipVia?ShipViaID=4

Example Response - Success

{

"SetShipViaResult": {

"error": {},

"response": {

"Cart.SetShipVia": {

"Success": true

}

}

}

}

Example Response - Failure

{

"SetShipViaResult": {

"error": {},

"response": {

"Cart.SetShipVia": {

"Error": "Could not find a Ship Via with an ID of 400."

}

}

}

}

Managing the cart

Once a cart has been created, its name can be changed or it can be deleted entirely.

Note: Beginning in version 16.04.108, carts are now deleted from database storage after 48 consecutive hours of inactivity. This is necessary for the prevention of database bloat, as carts were previously stored indefinitely. The user can resume their shopping session at any time within the time limit to reset the 48 hours of grace time before the cart is deleted.

Renaming the current cart - /Cart/Rename

Once a cart has been created, this call will be used to rename the cart itself.

Parameters

  • NewCartName - represents the desired name of the cart.

Example Call

http://localhost:8080/Cart/Rename?NewCartName=Example Cart Name

Example Response - Success

The below is an example of a successful call response.

{

"RenameResult": {

"error": {},

"response": {

"Cart.Rename": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid Cart ID.

{

"RenameResult": {

"error": {},

"response": {

"Cart.Rename": {

"Error": "Cart does not exist."

}

}

}

}

Deleting the current cart - /Cart/Delete

Once a cart is created and one or more parts have been added, this call will be used to delete the current cart entirely.

Parameters

  • KeepCart - Optional. A boolean parameter that defaults to False. When it is provided as true, the functionality will remove all contents from the cart but will retain the cart, rather than delete it, preventing the user from needing to call Cart/Create again to start the shopping process over again.

Example Call

http://localhost:8080/Cart/Delete

Example Response - Success

The below is an example of a successful call response.

{

"DeleteResult": {

"error": {},

"response": {

"Cart.Delete": {

"Success": true

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid Cart ID.

{

"DeleteResult": {

"error": {},

"response": {

"Cart.Delete": {

"Error": "Cart does not exist."

}

}

}

}

Checking out with the current cart - /Cart/Checkout

Once a cart is created and one or more parts have been added, this call will be used to take the contents of the cart and convert it to a DEACOM Sales Order. The contents of the cart will be cleared afterwards and the order number and order total will be returned. Note that a cart must be created and contents added to it (using /Cart/Create and /Cart/AddTo APIs, respectively) in order to perform the checkout process.

Beginning in version 16.04.150, if not using pre-payment Terms, all customers entering orders via this endpoint will have their credit checked before the order is successfully placed. The order may be refused or placed on credit hold if their credit is not sufficient.

Optional Parameters

  • IgnoreMasterOrder - If this parameter is true and there is only a single Ship-to, the order type will default to Sales Order instead of Master Order. Also, if this parameter is true, the Sales Order that is created will have its Ship-To, Ship Via, and Due To Ship Dates set based on how these fields are set on the cart/order lines. This will only occur when the eCommerce Default Order Type is set to Master Order and there is only a single distinct Ship-To among all order contents.
  • CardName - Name On Credit Card
  • PaymentType - ID of dmcash3 record being used (Payment Types)
  • CCNumber - Credit Card Number
  • CCExpDate - Credit Card Exp. Date
  • UseBillToAddress - checkbox on whether to use the BT address or CC address fields
  • CCStreet - Credit Card Street
  • CCStreet2 - Credit Card Street2
  • CCCity - Credit Card City
  • CCState - Credit Card State
  • CCZip - Credit Card Zip
  • CCCountry - Credit Card Country
  • StoreCCInfo - Should the card info be stored?
  • GiftCardID - ID of the dmgiftcard record in DEACOM
  • GiftCardNumber - gc_number of the dmgiftcard record in DEACOM
  • CreditCardID - The ID of an existing credit card to use for payment
  • EnforceCCLink - A true/false value indicating whether or not a check should occur to make sure that the CreditCardID passed in is linked to the current Bill-To. This defaults to true to ensure tighter security but can be overridden when passed in as false. An error message stating "The specified Credit Card is not linked to this session's Bill-To and cannot be used." will be returned if a Bill-To/Credit Card mismatch occurs while this value is true.
  • TermID - The ID of the Terms record in the dmterm table in DEACOM. The ID is used to set the terms on the order. When this parameter is passed through to this call, the to_teid (Terms ID) on the sales order created from the cart will be set to the ID passed through. The use of this parameter allows customers to select specific terms on orders. If no TermID parameter is specified, the terms on the order will be set to the terms specified on the Bill-To record.
  • KeepCart - This parameter defaults to true and controls whether or not the current cart remains active in the session after checking out. For example, if KeepCart = false, the cart is removed from the session after checkout and Cart/Create must be called again to start the shopping experience again.
  • OrderRemainingInventory - The quantity of available inventory in stock for this item. If this parameter is set to True, the system will bypass the error indicating that enough inventory does not exist and the item will not be added to the cart, and instead the system will add the maximum available inventory quantity of reaming inventory for this to the cart, in essence allowing the user to purchase as much as is available for the affected item. In this case an error message will not be displayed to the user and the system will reduce the amount on the order to the amount available.
  • DueShip - The sales order due to ship date. This paramater may effect both the sales order header and sales order line due to ship date depending on the following logic: 1. When an argument has been passed for DueShip, set the to_dueship field accordingly. The system already sets the or_dueship (so line) based on a cart value. The system will not override these line-level values if one has been set, but if no date has been set on each order line, the system will set it to to_dueship as well.
  • CCSecurityCode - This parameter is used to submit the 3-digit CVV code during a credit card transaction. Additionally, if the submitted Payment Type has the "Validation ID Required" flag checked in the main app, the CVV must be submitted upon eCommerce checkout or the payment will be rejected.
  • OrderType(string) - the DEACOM sales order type. When an argument has been passed for this parameter, the sytsem will set the cart property: OrderType to its value - You'll want to check Common.Enums.SalesOrderType for the legitimacy of the argument
  • Description - the to_descrip for the order. When an argument has been passed for "Description," the system will set to_descrip for the order to this value.
  • Promise - used to set the to_promise (Promised Date) on the sales order header.
  • Wanted - corresponds to the desired delivery date for this order. Value will be stored in the to_wanted field in the main application. Added in version 16.04.112.

Notes:

  • Beginning in version 16.04.127, the Cart/Checkout call will be prevented if the value in the "Maximum Cart Value" field (cs_maxcartvalue) is exceeded.
  • When either the GiftCardID or GiftCardNumber parameters is provided, the logic within Cart/Checkout will attempt to pay for the order using the gift card balance. The gift card must not be closed, and in the event that the balance on the gift card can not satisfy the full order, further payment methods must be provided using the credit card parameters available to this function. The gift card's remaining balance will be returned in the JSON response in the event that the gift card is applied successfully to the order.
  • The existing PaymentType parameter must also be specified when using CreditCardID so that a payment processing method (3 Delta, Payflow, etc) can still be determined. In the event that a CreditCardID is specified along with other optional credit card fields (CCNumber, CCExpDate, CCStreet, etc), these fields will be ignored and the stored credit card will be processed without regard to them. The result returned from this function is unchanged.
  • Carts have a ca_ordnum field which gets filled in which the Sales Order number after successful order creation. This field is useful for tracking which cart placed which order.
  • There is logic to automatically convert any cart level user-defined fields to Sales Order level user-defined fields upon checkout. User fields assigned to the cart are converted to Sales Order header fields in the main DEACOM application. User fields assigned to cart items are converted to Sales Order line user fields in the main DEACOM application.
  • The eCommerce Default Order Type can be set on the General tab via Tools > Maintenance > eCommerce Sites > Default Order Type.
  • When attempting to run the Cart/Checkout call, if there are no longer enough copies of the items on hand to satisfy the order, 1 of 2 behaviors will occur:
  • If the /Cart/Checkout endpoint was passed the new parameter, "OrderRemainingInventory" as true, the maximum available quantity of remaining inventory will be purchased for the affected item, even if it does not fill the order completely.
  • Otherwise, the /Cart/Checkout endpoint will throw an error and halt the checkout process.
  • Beginning in version 16.04.150, if not using pre-payment Terms, all customers entering orders via this endpoint will have their credit checked before the order is successfully placed. The order may be refused or placed on credit hold if their credit is not sufficient

Example Call

http://localhost:8181/Cart/Checkout

Example Call - using Gift Card Number

http://localhost:8181/Cart/Checkout?GiftCardNumber=2501893629939470

Example Response - Success (Sales Order)

The below is an example of a successful call response for a regular Sales Order.

{

"CheckoutResult": {

"error": {},

"response": {

"Cart.Checkout": {

"Success": true,

"Order Number": "2020-15530-00",

"Order ID": 8491,

"Order Subtotal": 35.95,

"Order Tax": 1.8,

"Order Total": 37.75,

"Order Contents": [

{

"PartID": 3700,

"PartNumber": "FINI1",

"Quant": 1.0,

"Price": 30.0,

"Extension": 30.0

},

{

"PartID": 3872,

"PartNumber": "Freight",

"Quant": 1.0,

"Price": 5.95,

"Extension": 5.95

},

{

"PartID": 0,

"PartNumber": "Pennsylvania",

"Quant": 1.0,

"Price": 1.8,

"Extension": 1.8

}

]

}

}

}

}

Example Response - Success (Master Order)

The below is an example of a successful call response for a Master Order.

{

"CheckoutResult": {

"error": {},

"response": {

"Cart.Checkout": {

"Success": true,

"Master Order Number": "2020-15528-00",

"Master Order ID": 8489,

"Master Order Subtotal": 35.95,

"Master Order Tax": 1.8,

"Master Order Total": 37.75,

"Master Order Contents": [

{

"PartID": 3700,

"PartNumber": "FINI1",

"Quant": 1.0,

"Price": 30.0,

"Extension": 30.0

},

{

"PartID": 3872,

"PartNumber": "Freight",

"Quant": 1.0,

"Price": 5.95,

"Extension": 5.95

},

{

"PartID": 7777,

"PartNumber": "Master order dummy",

"Quant": 1.0,

"Price": 1.8,

"Extension": 1.8

}

],

"Child Orders": [

{

"ChildOrderNumber": "2020-15529-00",

"ChildOrderID": 8490,

"ChildOrderSubtotal": 35.95,

"ChildOrderTax": 1.8,

"ChildOrderTotal": 37.75,

"ShipTo": "Default eCommerce",

"ShipVia": "Crane",

"Freight": "Prepaid and Add",

"OrderedItems": [

{

"PartID": 3700,

"PartNumber": "FINI1",

"Quant": 1.0,

"Price": 30.0,

"Extension": 30.0

},

{

"PartID": 3872,

"PartNumber": "Freight",

"Quant": 1.0,

"Price": 5.95,

"Extension": 5.95

},

{

"PartID": 0,

"PartNumber": "Pennsylvania State Tax",

"Quant": 1.0,

"Price": 1.8,

"Extension": 1.8

}

]

}

]

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of using an invalid Cart ID or if the Cart does not contain any items.

{

"Cart.Checkout": {

"Error": "The specified Cart contains no items."

}

}

Checking out with the current cart - /Cart/CheckoutPost

As of version 16.04.096, the user can also use a POST request instead of the GET request above to checkout. This process simply requires language changes in Cart.Checkout to Cart.CheckoutPost and carries a distinct advantage over the GET call - being less prone to exposing sensitive user data if the database is compromised by an attacker. The respective example responses above will remain the same, with the minor difference of having "Post" connected to Cart.Checkout. POST requests are also available for User/LoginPost.

Notes

  • The Wanted parameter was added to this call beginning in version 16.04.112. This optional parameter corresponds to the desired delivery date for this order. Value will be stored in the to_wanted field in the main application.
  • Beginning in version 16.04.127, the Cart/CheckoutPost call will be prevented if the value in the "Maximum Cart Value" field (cs_maxcartvalue) is exceeded.
  • Beginning in version 16.04.150, if not using pre-payment Terms, all customers entering orders via this endpoint will have their credit checked before the order is successfully placed. The order may be refused or placed on credit hold if their credit is not sufficient.

Optional Parameters

  • Promise - used to set the to_promise (Promised Date) on the sales order header.
  • Creating orders without a cart
  • The Cart/CreateOrder API call is used to create a sales order in the DEACOM eCommerce application without the need to create a cart. This option is useful for Shopify integrations.
  • Creating orders without a cart - /Cart/CreateOrder
  • This method works as an alternative to Cart/Checkout, with the same functionality, but without the need for calls such as Cart/Create or Cart/AddTo to occur beforehand. This eliminates the need to maintain a cart and session object and allows for customers who have a front end site already in place to access Deacom with a quicker one-off API call. Note that at this time a site must still be set up from Tools > Maintenance > eCommerce Sites in order to use this API as all of our functions require a SiteID parameter to be specified.

Notes

  • Beginning in version 16.07.072, this API call has been completely transitioned into an HTTP POST call, rather than HTTP GET. This allows the creation of highly complex orders without running into URL length restrictions imposed by the HTTP GET protocol, as well as the correct parsing of special characters that would otherwise be URL encoded. When using the HTTP POST option, parameters can be placed in the body using JSON.
  • Beginning in version 16.04.150, if not using pre-payment Terms, all customers entering orders via this endpoint will have their credit checked before the order is successfully placed. The order may be refused or placed on credit hold if their credit is not sufficient.

Required Parameters

  • Order Header - a string containing the contents of the order header. The following order header fields can be specified in this parameter:
  • biid - the Bill-To ID
  • shid - the Ship-To ID
  • trid - the Ship Via method ID
  • brid(optional) - the Broker ID, if any
  • deliverydate - the desired delivery date of the order. Note: Beginning in version 16.05.116, if the delivery date field on the cart is populated during checkout, that date will be saved on the resulting Sales Order in the Due to Ship ("to_dueship") field.
  • notes(optional) - the order header notes, if any
  • ponum(optional) - the Bill-To company PO, if any

Notes:

  • The OrderHeader parameter should be formatted as "field":value, "field":value, with curly braces {} surrounding it, in order to be parsed properly. Example: {"biid":2218,"shid":2698,"trid":6,"brid":0,"deliverydate":"02/01/2020","notes":"Test Note","ponum":"Test ponum"}
  • Beginning in version 16/07.058, when running "Cart/CreateOrder", if a Master Order is created, the UDF values specified in the "OrderHeader" parameter will be applied to that Master Order's header as well as all Child Order headers linked to it. Additionally, UDF Values are now able to be specified in this call by field name if desired.
    • Order Lines - a string containing the contents of the order lines. The following order line fields can be specified in this parameter:
    • prid - the Part ID
    • quant - the quantity being ordered
    • notes(optional) - the notes for this part, if any
    • price(optional) - a manually entered decimal value for the price of a line item
  • The OrderLines parameter should be formatted with each order line designated as "field":value, "field":value. Each order line should be surrounded by curly braces {} with the entire parameter enclosed in square braces []. Example: [{"prid":3700,"quant":2,"notes":"TestNote"},{"prid":5356,"quant":1}]. Also, beginning in version 16.07.054, the OrderLines parameter was modified to all ship-to,ship via, delivery date, and line-level user fields can be specified. Also, the logic in the BuildOrderFromString() function has been expanded so that child orders are built up at this stage before the master order is saved and processed.
  • Beginning in version 16/07.058, when running "Cart/CreateOrder", if a Master Order is created, UDF values specified in the "OrderLines" parameter will be applied to the lines on the Sales Order. Additionally, UDF Values are now able to be specified in this call by field name if desired.
  • Credit Card Authorization Handling - Beginning in version 16.07.065, when using this API call, prior credit card authorizations will now be correctly applied when checking out. Orders that have been created with prior authorizations can now be modified and shipped successfully. Note: When only an authorization token is supplied without full credit card details the authorization on the order can be voided or captured. However, if the order total changes, a new authorization can't be done without entering the credit card information.

Optional Parameters (these are the same as /Cart/Checkout)

  • IgnoreMasterOrder - If this parameter is true and there is only a single Ship-to, the order type will default to Sales Order instead of Master Order.
  • CardName - Name On Credit Card
  • PaymentType - ID of dmcash3 record being used (Payment Types)
  • CCNumber - Credit Card Number
  • CCExpDate - Credit Card Exp. Date
  • UseBillToAddress - checkbox on whether to use the BT address or CC address fields
  • CCStreet - Credit Card Street
  • CCStreet2 - Credit Card Street2
  • CCCity - Credit Card City
  • CCState - Credit Card State
  • CCZip - Credit Card Zip
  • CCCountry - Credit Card Country
  • StoreCCInfo - Should the card info be stored?
  • GiftCardID - ID of the dmgiftcard record in DEACOM
  • GiftCardNumber - gc_number of the dmgiftcard record in DEACOM
  • CreditCardID - The ID of an existing credit card to use for payment
  • EnforceCCLink - A true/false value indicating whether or not a check should occur to make sure that the CreditCardID passed in is linked to the current Bill-To. This defaults to true to ensure tighter security but can be overridden when passed in as false. An error message stating "The specified Credit Card is not linked to this session's Bill-To and cannot be used." will be returned if a Bill-To/Credit Card mismatch occurs while this value is true.
  • CCSecurityCode - This parameter is used to submit the 3-digit CVV code during a credit card transaction. Additionally, if the submitted Payment Type has the "Validation ID Required" flag checked in the main app, the CVV must be submitted upon eCommerce checkout or the payment will be rejected.
  • AuthAmt - Authentification of Credit Card amount. If entered, user must provide valid information for AuthAmt, AuthC3ID, AuthDate, AuthToken, and CCLast4.
  • AuthC3ID - Authentification of Credit Card ID. If entered, user must provide valid information for AuthAmt, AuthC3ID, AuthDate, AuthToken, and CCLast4.
  • AuthDate - Authentification of Credit Card Exp. Date. If entered, user must provide valid information for AuthAmt, AuthC3ID, AuthDate, AuthToken, and CCLast4.
  • AuthToken - Authentification of Credit Card token. If entered, user must provide valid information for AuthAmt, AuthC3ID, AuthDate, AuthToken, and CCLast4.
  • CCLast4 - Authentification of Credit Card last 4 numbers. If entered, user must provide valid information for AuthAmt, AuthC3ID, AuthDate, AuthToken, and CCLast4.
  • TermID - Term ID

Example Call

http://localhost:8181/Cart/CreateOrder?OrderHeader={"biid":2218,"shid":2698,"trid":6,"brid":0,"deliverydate":"02/01/2020","notes":"Test Note","ponum":"Test ponum"}&OrderLines=[{"prid":3700,"quant":2,"notes":"TestNote"},{"prid":5356,"quant":1}]

Example Response - Success

{

"CreateOrderResult": {

"error": {},

"response": {

"Cart.CreateOrder": {

"Success": true, "Order Number": "2020-14985-00", "Order ID": 7858, "Order Total": 63.6

}

}

}

}

Example Response - Failure

{

"CreateOrderResult": {

"error": {

"type": "nonFatal",

"exceptionType": "DeacomException",

"message": "Could not determine an active Bill-To for the given ID."

},

"response": {}

}

}

Cancelling Orders - /User/CancelOrder

The OrderCancel API call allows users to cancel the specified order number. The shipping status will then return "Cancelled" for this order on the new record. Beginning in version 16.07.110, this endpoint has it's security updated. Only the user who actually placed the order is allowed to cancel the order. Stateless API users are also able to do this for any order, as Stateless users are administrators. This logic also applies to the "Order/AddLine", "Order/Update", "Order/UpdateLine", and "Order/DeleteLine" endpoints

Note: Beginning in version 16.07.110, this endpoint (and the "Order/AddLine", "Order/Update", "Order/UpdateLine", and "Order/DeleteLine" endpoints) have their security updated. Only the user who actually placed the order is allowed to cancel the order. Stateless API users are also able to do this for any order, as Stateless users are administrators.

Parameters

  • OrderNumber

Example Call

http://localhost:8181/Order/cancel?OrderNumber=(from your new order)

Updating Orders

The OrderUpdate and OrderUpdateLine API calls allow users to update Ship-To ID, Notes, Frequency, Interval, and Quantity for recurring orders that are already placed. Beginning in version 16.07.110, the security has been updated for the Order/Update and Order/UpdateLine endpoints. Only the user who actually placed the order is allowed to cancel the order.

Update Order - /Order/Update

Parameters

  • OrderNumber
  • NewValues - JSON object, fields available to pass in:
  • to_shid (Ship-To ID) - Cannot be changed on orders that have a payment already placed against it, or if the field is disabled for the order in the main app.
  • to_notes (Notes)
  • to_recurtype (Frequency)
  • to_recurinterval (Interval)

Update Order Line - /Order/UpdateLine

Parameters

  • OrderLineID
  • NewValues

Leaving Product Reviews

The SetProductReview and GetProductReviews API calls allow users to leave product reviews and have these reviews stored within DEACOM.

Set product reviews - /General/SetProductReview

Parameters

  • ReviewID
  • SiteID - Multiple sites can be established in the DEACOM's eCommerce offering. The SiteID indicates the ID number for the site where the product reviews are located.
  • Name
  • Title
  • Date
  • PartID - the pr_id of the DEACOM part number
  • Review
  • Rating
  • Visible
  • Anonymous - Determines if the ID of the user will be included when posting a review. Set to False to have ID included. Set to True to not have ID included. Added in version 16.04.122. (Note: the rv_cuid was added to the dtprodreviews table in order to store this ID number)

An existing review may be edited if the ReviewID parameter is passed and the currently logged in user owns the review connected to the specific ReviewID. In this case, the chosen review will be updated based on the parameters that were passed instead of creating a new review.

If ReviewID is not provided, API assumes that a new record is to be created. SiteID, PartID, and Review are required and will be validated.

Example Call

http://localhost:8080/General/SetProductReview?PartID=4072&SiteID=1&Name=John Doe&Review=Pleasantly surprised.&Rating=4

If ReviewID is provided, API assumes that an existing record is to be modified. All other fields are optional. If a SiteID and/or PartID are provided, they will be validated. Any field not provided will remain unchanged. Note that, unlike in the "Edit eCommerce Product Review" form in Deacom, the SiteID, PartID, and Date can be modified.

Example Call

http://localhost:8080/General/SetProductReview?ReviewID=28&SiteID=1&Visible=true&Anonymous=false (this example has the "Anonymous" parameter (added in version 16.04.122) set to false which means the ID of the user who posted the review will be included)

Example Call

http://localhost:8080/General/SetProductReview?ReviewID=28&SiteID=1&Visible=true

Example Response - Success

{

"SetProductReviewResult": {

"error": {},

"response": {

"General.SetProductReview": {

"Success": "Created Product Review With ID = 51"

}

}

}

}

Example Response - Failure - Invalid Part ID

{

"SetProductReviewResult": {

"error": {},

"response": {

"General.SetProductReview": {

"Error": "You must provide a valid PartID to add a new product review."

}

}

}

}

Get product review - /General/GetProductReviews

Parameters

  • ReviewID
  • PartID - the pr_id of the DEACOM part number
  • SiteID - Multiple sites can be established in the DEACOM's eCommerce offering. The SiteID indicates the ID number for the site where the product reviews are located.

If ReviewID is provided, API will attempt to return the product review with that ID.

Example Call

http://localhost:8080/General/GetProductReviews?ReviewID=1

If ReviewID is not provided, PartID and SiteID must both be provided. API will attempt to return all reviews for the given part on that site. Note: SiteID is necessary to distinguish between multiple possible sites.

Example Calls

http://localhost:8080/General/GetProductReviews?PartID=3717&SiteID=3

http://localhost:8080/General/GetProductReviews?PartID=3717&SiteID=3&ReviewID=42 (this example call includes the ReviewID field. (Note that, beginning in version 16.04.122, the /General/SetProductReview call contains the "Anonymous" parameter which controls if the ID of the user posting the review will be captured.)

Example Response - Success

{

"GetProductReviewsResult": {

"error": {},

"response": {

"General.GetProductReviews": {

"44": {

"Item1": "44",

"Item2": {

"rv_id": 44,

"rv_name": " Joan Doe",

"rv_title": "FINI1 Review",

"rv_review": "Not bad at all.",

"rv_rating": 88,

"rv_prid": 3700,

"rv_date": {

"IsNull": false,

"Value": "2019-03-01T16:37:27.523",

"DayTicks": 43523,

"TimeTicks": 17954257

},

"rv_visible": true,

"rv_csid": 3

}

},

"51": {

"Item1": "51",

"Item2": {

"rv_id": 51,

"rv_name": "",

"rv_title": "",

"rv_review": "This product stinks!",

"rv_rating": 0,

"rv_prid": 3700,

"rv_date": {

"IsNull": false,

"Value": "2019-04-05T10:55:23.35",

"DayTicks": 43558,

"TimeTicks": 11797005

},

"rv_visible": false,

"rv_csid": 3

}

},

"52": {

"Item1": "52",

"Item2": {

"rv_id": 52,

"rv_name": "",

"rv_title": "",

"rv_review": "This product is great!",

"rv_rating": 0,

"rv_prid": 3700,

"rv_date": {

"IsNull": false,

"Value": "2019-04-05T10:57:17.507",

"DayTicks": 43558,

"TimeTicks": 11831252

},

"rv_visible": false,

"rv_csid": 3

}

}

}

}

}

}

Example Response - Failure

{

"GetProductReviewsResult": {

"error": {},

"response": {

"General.GetProductReviews": {

"DeacomError": "Error: Could not find any reviews for the provided product and site."

}

}

}

}

Checking gift card balances

The CheckGiftCardBalance API call checks the remaining balance on gift cards through eCommerce. This function will find the gift card number specified and return the balance (if any) left on the card. Note that gift cards can be generated in Deacom by going to Accounting > Accounting Maintenance > Gift Cards.

Check gift card balance - General/CheckGiftCardBalance

Parameters

  • GiftCardNumber - the gift card number

Example Call

http://localhost:8181/General/CheckGiftCardBalance?GiftCardNumber=2501893629939472

Example Response - Success

{

"CheckGiftCardBalanceResult": {

"error": {},

"response": {

"General.CheckGiftCardBalance": {

"Success": true,

"Balance": 25.0

}

}

}

}

Example Response - Failure

{

"CheckGiftCardBalanceResult": {

"error": {},

"response": {

"General.CheckGiftCardBalance": {

"Error": "Could not find an active gift card with the specified gift card number."

}

}

}

}

Obtaining available shipping via methods

When called, this function will return information relevant to active ship via methods created in Deacom, including ID, name, service type, carrier type, and minimum order amount.

Obtain all available shipping via methods for a user - General/GetShipViaMethods

Parameters

  • ShipViaID (optional) - the specific ID of the ship via method to filter on

Example Call

http://localhost:8181/General/GetShipViaMethods

Example Response - Success

{

"GetShipViaMethodsResult": {

"error": {},

"response": {

"General.GetShipViaMethods": {

"ShipViaMethods": [

{

"ID": 1,

"Name": "UPS",

"ServiceType": "2nd Day Air",

"MinAmount": "$15.00"

},

{

"ID": 2,

"Name": "Federal Express",

"ServiceType": "INTERNATIONAL_PRIORITY",

"MinAmount": "$0.00"

},

{

"ID": 3,

"Name": "Roadway Express",

"ServiceType": "",

"MinAmount": "$0.00"

},

{

"ID": 4,

"Name": "USPS",

"ServiceType": "None",

"MinAmount": "$0.00"

},

{

"ID": 7,

"Name": "DHL",

"ServiceType": "None",

"MinAmount": "$0.00"

},

{

"ID": 21,

"Name": "FedEx Freight",

"ServiceType": "FEDEX_FREIGHT_PRIORITY",

"MinAmount": "$0.00"

},

{

"ID": 22,

"Name": "FedEx Express Freight",

"ServiceType": "FEDEX_FIRST_FREIGHT",

"MinAmount": "$0.00"

},

{

"ID": 24,

"Name": "FedEx GROUND",

"ServiceType": "FEDEX_GROUND",

"MinAmount": "$0.00"

},

{

"ID": 27,

"Name": "USPS Priority",

"ServiceType": "Priority",

"MinAmount": "$0.00"

},

{

"ID": 28,

"Name": "FedEx Home",

"ServiceType": "GROUND_HOME_DELIVERY",

"MinAmount": "$0.00"

}

]

}

}

}

}

Example Response - Failure

{

"GetShipViaMethodsResult": {

"error": {},

"response": {

"General.GetShipViaMethods": {

"Error": "Ship Via information could not be found."

}

}

}

}

Obtain Order Information and Images/Files

Obtain all order information and images/files - /Order/GetData

This API call will return all order information, including any images or files attached to the order based on the order number specified in the call.

Required Parameters

  • OrderNumber - the DEACOM sales order number (to_ordnum)

Example Call

http://localhost:8181/Order/GetData?&pcOrderNumber=20210852300

Example Response - Success

Example Response - Failure

Obtain all information for multiple orders - /Order/GetMultiple

This API call will retrieve sales order details for a single sales order or multiple sales orders, given the specific filters chosen.

Required Parameters

  • OrderedStartDate - related to to_ordered

Optional Parameters

  • OrderedEndDate - related to to_ordered
  • Facility - related to to_waid
  • BillToID - related to to_biid
  • ShipToID - related to to_shid
  • OrderNumber - related to to_ordnum
  • MasterOrderNumber - related to to_masterordnum
  • Additional Fields - a comma-separated list of field names used to specify any additional fields that should be returned in the response of this function. Any fields that can be added as a grid column in the main app Sales Order Detail grid can be specified here to be returned, including user fields. Note: all Header UDFs and Line UDFs are returned under a singular response object.

Note: This API should return the same way as User/GetOrderHistoryDetail call does, but with additional fields. Also, the to_saved and to_recdate fields in the response indicate the most recent modified date.

Example Calls

Start date - http://localhost:8181/Order/GetMultiple?OrderedStartDate=3-08-2022

Specific sales order number - http://localhost:8181/Order/GetMultiple?OrderedStartDate=3-08-2022&OrderNumber=2022076818800

Order end date - add a start date of a while back and an end date directly before the date of creating your sales orders - http://localhost:8181/Order/GetMultiple?OrderedStartDate=3-08-2022&OrderedEndDate=3-09-2022

Specific Facility - use the ID of the to_waid (facility) that your Sales Order is assigned to - http://localhost:8181/Order/GetMultiple?OrderedStartDate=3-08-2022&Facility=1

Specific Bill-To - http://localhost:8181/Order/GetMultiple?OrderedStartDate=3-08-2022&BillToID=143332

Specific Ship-To - http://localhost:8181/Order/GetMultiple?OrderedStartDate=3-08-2022&ShipToID=985951

Master Order Number - http://localhost:8181/Order/GetMultiple?OrderedStartDate=3-08-2022&MasterOrderNumber=1

Example Response - Success

{

"GetMultipleResult": {

"error": {},

"response": {

"Order.GetMultiple": {

"Success": true,

"Orders": [

{

"bi_name": "4 STATE SUPPLY",

"or_exten": 90.0,

"or_ordquant": 3.0,

"or_price": 30.0,

"or_prid": 3700,

"or_shipquant": 0.0,

"pr_codenum": "FINI1",

"sh_name": "4 STATE SUPPLY",

"to_balance": 90.0,

"to_biid": 977,

"to_confirm": "",

"to_dueship": "06/23/2022",

"to_masterordnum": 0.0,

"to_orddate": "06/09/2022",

"to_ordered": "06/09/2022",

"to_ordnum": 20221757000.0,

"to_ordtype": "s",

"to_condate": "06/10/2022",

"to_paydate": "",

"to_recdate": "06/10/2022",

"to_saved": "06/10/2022",

"to_shid": 1578,

"to_shipped": "",

"to_totdue": 90.0,

"to_waid": 2,

"tr_name1": "CamDSD"

},

{

"bi_name": "4 STATE SUPPLY",

"or_exten": 0.0,

"or_ordquant": 10.0,

"or_price": 0.0,

"or_prid": 5356,

"or_shipquant": 0.0,

"pr_codenum": "Matt Part 3",

"sh_name": "4 STATE SUPPLY",

"to_balance": 90.0,

"to_biid": 977,

"to_confirm": "",

"to_dueship": "06/23/2022",

"to_masterordnum": 0.0,

"to_orddate": "06/09/2022",

"to_ordered": "06/09/2022",

"to_ordnum": 20221757000.0,

"to_ordtype": "s",

"to_paydate": "",

"to_recdate": "06/10/2022",

"to_saved": "06/10/2022",

"to_shid": 1578,

"to_shipped": "",

"to_totdue": 90.0,

"to_waid": 2,

"tr_name1": "CamDSD"

},

{

"bi_name": "4 STATE SUPPLY",

"or_exten": 0.1,

"or_ordquant": 1.0,

"or_price": 0.1,

"or_prid": 5172,

"or_shipquant": 0.0,

"pr_codenum": "#10-16 T/3-2",

"sh_name": "4 STATE SUPPLY",

"to_balance": 0.1,

"to_biid": 977,

"to_confirm": "",

"to_dueship": "06/17/2022",

"to_masterordnum": 0.0,

"to_orddate": "06/02/2022",

"to_ordered": "06/02/2022",

"to_ordnum": 20221756900.0,

"to_ordtype": "s",

"to_paydate": "",

"to_recdate": "06/02/2022",

"to_saved": "06/02/2022",

"to_shid": 1578,

"to_shipped": "",

"to_totdue": 0.1,

"to_waid": 2,

"tr_name1": "CamDSD"

}

]

}

}

}

}

Example Response - Failure

An example failure would state: "Could not find any orders for the given User and the specified parameters."

Shipping Orders

Ship Sales Orders - /Order/Ship

This API will ship an order using the materials specified. Note: If the main app system option "Invoice at Shipment" is checked, this API function will also invoice the selected Sales Order. Keep this in mind when using this functionality.

Required Parameters

  • OrderID - ID of the Order
  • LotProperties - a string containing the contents of the lots to ship. The string contains comma-separated key/value pairs of lot information. Each individual lot should be wrapped inside curly braces {} and the entire string should start and end with square braces. An example of the formatting for LotProperties can be seen below:

[{"prid":5356,"quant":3,"userlot":"MW1002","lotnum":13931,"loid":17, "orid":10692},{"prid":5356,"quant":3,"userlot":"MW1002","lotnum":13931,"loid":17,"orid":10693}]

The properties available to the LotProperties parameter are as follows:

  • orid -- the ID of the Sales Order line that the lot info is being shipped for (or_id)
  • prid -- the Deacom part ID that is being shipped (pr_id)
  • quant -- the quantity being shipped from the lot. Note that whatever is provided for the quant parameter will be shipped, so be careful not to over- or under-ship requirements for an order.
  • userlot -- the Deacom user lot that is being shipped (fi_userlot)
  • lotnum (optional) -- the Deacom lot number to be shipped (fi_lotnum)
  • loid (optional) -- the Location ID of the lot to be shipped (fi_loid)
  • attrib1 (optional) -- the attribute 1 of the lot to be shipped (fi_attrib1)
  • attrib2 (optional) -- the attribute 2 of the lot to be shipped (fi_attrib2)
  • attrib3 (optional) -- the attribute 3 of the lot to be shipped (fi_attrib3)

Optional Paramteters

Facility - Facility specified on the sales order in DEACOM. When a value is passed into the call for the Facility parameter, the value is used as the facility in to_waid of the order being created. If unspecified, the default facility will be used. If no default exists, the first active facility will be used.

Example Call

[{"prid":5356,"quant":3,"userlot":"MW1002","lotnum":13931,"loid":17, "orid":10695},{"prid":5356,"quant":3,"userlot":"MW1002","lotnum":13931,"loid":17,"orid":10696}]

Example Response - Success

{

"ShipResult": {

"error": {},

"response": {

"Order.Ship": {

"Success": true

}

}

}

}

Example Response - Failure

Example failure response:

{

"ShipResult": {

"error": {},

"response": {

"Order.Ship": {

"Success": false,

"Error": "Insufficient Inventory for SJ-20201412900.\r\nItem FINI1 in user lot MW1002 is short 3 out of 3.\r\nItem FINI1 in user lot MW1002 is short 3 out of 3.\r\n"

}

}

}

}

Potential Failure Scenarios:

  • The order number passed in does not exist.
  • The order number passed in has already been shipped
  • Insufficient inventory -- usually due to incorrect fields passed in via LotProperties that do not correspond to lots within Deacom
  • One or more of the following required fields were not included in the LotProperties parameter: orid, prid, quant, userlot

Invoicing and paying an order

Invoicing and paying an order in eCommerce - /Order/InvoicePay

This API call will invoice and pay the order specified in OrderID in DEACOM, ensuring all Invoice and Payment GL postings are made against the order. The payment posting will be made against the account on the payment type (dmcash3.c3_chid) and the Payment Type should be used as the ca_c3id in dtcash. The API will check that any order passed in is already shipped (to_shipped is not empty) prior to allowing the order to be invoiced. Note: as a result of this API, the /Cart/CreateOrder API now contains logic to set the default order type based on the configuration of the site in the main DEACOM application. This had previously always defaulted to "Internet Sale" previously, which does not allow the order to be shipped/invoiced.

Parameters

  • OrderNumber (required) -- The deacom order number (dttord.to_ordnum) to invoice and ship.
  • PaymentType* -- The payment type ID (dmcash3.c3_id) for general ledger information to populate with.
  • Payment* - a string containing comma-separated key/value pairs of payment information. Each individual payment should be wrapped inside curly braces {} and the entire string should start and end with square braces. An example of the formatting for the Payments parameter is here: [{"c3id":"3","amount":"20"},{"c3id":"1","amount":"12.4"}] The properties available to the Payments parameter are as follows: c3id -- the ID of the payment type to apply (dmcash3.c3_id) and amount -- the dollar amount to apply
  • Note* - Beginning in version 16.01.061 the PaymentType (integer) parameter has been removed and replace with a new Payments parameter (string). The OrderNumber parameter remains unchanged and must still be included. An example business case for needing splitting payments types is: Canpay, the only approved non-cash payment method for dispensary payments, has a $500 limit. For customers who order over $500, the first $500 comes over via Canpay, and the remainder is paid in cash. For accounting purposes, we will need to be able to log the different payment methods in the system.

Example Calls

http://localhost:8181/Order/InvoicePay?OrderNumber=20201417600&PaymentType=3

With multiple payment types - http://localhost:8181/Order/InvoicePay?OrderNumber=20201419700&Payments=[{"c3id":"3","amount":"20"},{"c3id":"1","amount":"12.4"}]

Note: The success and failure responses remain the same. However, two new failure conditions have been added:

  • if one or both of the properties in the Payments parameter were not included (c3id, amount)
  • if the sum of the payments does not match the total amount due for the order.

Example Response - Success

{

"InvoicePayResult": {

"error": {},

"response": {

"Order.InvoicePay": {

"Success": true

}

}

}

}

Example Response - Failure

{

"InvoicePayResult": {

"error": {},

"response": {

"Order.InvoicePay": {

"Success": false,

"Error": "This order has already been invoiced and paid."

}

}

}

}

Potential failure scenarios:

  • Could not find a Sales Order with an order number of (OrderNumber).
  • This order has already been invoiced and paid.
  • The provided PaymentType is invalid.
  • Failed to invoice order -- occurs when a general failure occurs during invoicing process (same errors as main app)
  • Failed to apply payment -- occurs when a general failure occurs during payment process (same errors as main app)

Managing credit card information

Gathering credit card information - /BillTo/GetCreditCards

This API does not take any parameters. The API is used for checking out with a stored credit card. It will return details for all credit cards linked to the Bill-To of the session's user. Fields include the card's ID, cardholder name, the last 4 digits, expiration date in MMYY format, payment type, Use Bill To Address flag, and the credit card address fields.

Example Call

http://localhost:8181/BillTo/GetCreditCards

Example Response - Success

{

"GetCreditCardsResult": {

"error": {},

"response": {

"BillTo.GetCreditCards": {

"Cards": [

{

"ID": 32,

"Name": "Test JG",

"Last4": "1111",

"Expiration": "02/22",

"PaymentType": "Visa",

"UseBillToAddress": 1,

"AddressStreet": "",

"AddressStreet2": "",

"AddressCity": "",

"AddressState": "",

"AddressCountry": "",

"AddressZip": ""

}

]

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of the Bill-To record not having any linked credit cards.

{

"GetCreditCardsResult": {

"error": {},

"response": {

"BillTo.GetCreditCards": {

"Error": "This Bill-To does not have any credit cards stored to it."

}

}

}

}

Add credit card information - /BillTo/AddCreditCard

This API adds credit card information from eCommerce into DEACOM. When this API is called, the system adds a new dmccard record in DEACOM for the Bill-To in the current session. Note: Beginning in version 16.04.127, this API call has been converted to a POST request in order to allow for credit card numbers to be obscured which greatly improves the security of the transmitted data.

Required Parameters

  • CardName - Name On Credit Card
  • PaymentType - ID of dmcash3 record being used (Payment Types)
  • CCNumber - Credit Card Number
  • CCExpDate - Credit Card Exp. Date
  • UseBillToAddress - checkbox on whether to use the BT address or CC address field
  • Default - sets the credit card as the default for the account. True/False values. The user can only have 1 card set as default. Deleting the default card with "BillTo/DeleteCreditCard" API will assign the next available saved credit card as default (if available). Adding a new default card or modifying another card to add the default flag will remove the default flag from all other cards.

Optional Parameters

  • CCStreet - Credit Card Street
  • CCStreet2 - Credit Card Street2
  • CCCity - Credit Card City
  • CCState - Credit Card State
  • CCZip - Credit Card Zip
  • CCCountry - Credit Card Country

Example Call

http://localhost:8181/BillTo/AddCreditCard?CardName=Test Name&PaymentType=2&CCNumber= 1111 1111 1111 1111&CCExpDate=520

Example Response - Success

"AddCreditCardResult": {

"error": {},

"response": {

"BillTo.AddCreditCard": {

"Success": {

"Authorize": 0.0,

"Charge": 0.0,

"TempCVV2": null,

"ID": 3978,

"Last4": "1111",

"BillToCompany": {

…

},

"Street": "f",

"Street2": "f",

"City": "f",

"State": "f",

"Zip": "12345",

"Country": "United States",

"LogChanges": true,

"cc_id": 3978,

"cc_number": "DA031EB706648B2062269208A48BB0FFA9BF5152DFF8A8BDE17542A79969CACDBA43CC2B21284FEB3C82FDB573659C33",

"cc_nameoncard": "Test Name",

"cc_exp": 520,

"cc_c3id": 2,

"cc_billaddr": true,

"cc_street": "f",

"cc_street2": "f",

"cc_city": "f",

"cc_state": "f",

"cc_zip": "12345",

"cc_country": "United States",

"cc_biid": 2115,

"cc_last4": "1111",

"cc_ordnum": 0.0,

"cc_billpo": " ",

"cc_cardvaultid": " ",

"AutoSync": false,

"TransStarted": false,

"IDField": "cc_id",

"IDAlias": "",

"SyncObject": null,

"LogRecordId": 3978.0,

"Query": {

…

},

"SyncQuery": null,

"ActiveField": null,

}

}

}

Example Response - Failure

{

"AddCreditCardResult": {

"error": {},

"response": {

"BillTo.AddCreditCard": {

"Error": [

"An invalid date was passed in argument for parameter CCExpDate.”

]

}

}

}

}

Update Credit Card Information - /BillTo/UpdateCreditCard

This API updates credit card information from eCommerce into DEACOM. Notes:

CC Numbers cannot be updated. That would require a delete and add.

Beginning in version 16.04.127, this API call has been converted to a POST request in order to allow for credit card numbers to be obscured which greatly improves the security of the transmitted data.

Required Parameters

  • CreditCardID - ID of the dmccard record assigned to the Bill-To
  • Default - sets the credit card as the default for the account. True/False values. The user can only have 1 card set as default. Deleting the default card with "BillTo/DeleteCreditCard" API will assign the next available saved credit card as default (if available). Adding a new default card or modifying another card to add the default flag will remove the default flag from all other cards.

Optional Parameters

  • CardName - Name On Credit Card
  • PaymentType - ID of dmcash3 record being used (Payment Types)
  • CCExpDate - Credit Card Exp. Date
  • CCCvv2 - CCV2
  • UseBillToAddress - checkbox on whether to use the BT address or CC address fields
  • CCStreet - Credit Card Street
  • CCStreet2 - Credit Card Street2
  • CCCity - Credit Card City
  • CCState - Credit Card State
  • CCZip - Credit Card Zip
  • CCCountry - Credit Card Country

Example Call

http://localhost:8181/BillTo/UpdateCreditCard?CreditCardID=3978&CardName=TestName McTestName&UseBillToAddress=false

Example Response - Success

"UpdateCreditCardResult": {

"error": {},

"response": {

"BillTo.UpdateCreditCard": {

"Success": {

"Authorize": 0.0,

"Charge": 0.0,

"TempCVV2": null,

"ID": 3978,

"Last4": "1111",

"BillToCompany": {

…

},

"Street": "f",

"Street2": "f",

"City": "f",

"State": "f",

"Zip": "12345",

"Country": "United States",

"LogChanges": true,

"cc_id": 3978,

"cc_number": "DA031EB706648B2062269208A48BB0FFA9BF5152DFF8A8BDE17542A79969CACDBA43CC2B21284FEB3C82FDB573659C33",

"cc_nameoncard": "TestName McTestName",

"cc_exp": 520,

"cc_c3id": 2,

"cc_billaddr": false,

"cc_street": "f",

"cc_street2": "f",

"cc_city": "f",

"cc_state": "f",

"cc_zip": "12345",

"cc_country": "United States",

"cc_biid": 2115,

"cc_last4": "1111",

"cc_ordnum": 0.0,

"cc_billpo": "",

"cc_cardvaultid": "",

"AutoSync": false,

"TransStarted": false,

"IDField": "cc_id",

"IDAlias": "",

"SyncObject": null,

"LogRecordId": 3978.0,

"Query": {

…

},

"SyncQuery": null,

"ActiveField": null

}

}

}

}

}

Example Response - Failure

{

"UpdateCreditCardResult": {

"error": {},

"response": {

"BillTo.UpdateCreditCard": {

"Error": [

"No argument passed for required parameter CreditCardID”

]

}

}

}

}

Delete Credit Card Information - /BillTo/DeleteCreditCard

This API deletes credit card information from eCommerce into DEACOM.

Required Parameters

  • CreditCardID - ID of the dmccard record assigned to the Bill-To

Example Call

http://localhost:8181/BillTo/DeleteCreditCard?CreditCardID=3977

Example Response - Success

{

"DeleteCreditCardResult": {

"error": {},

"response": {

"BillTo.DeleteCreditCard": {

"Success": {}

}

}

}

}

Example Response - Failure

{

"DeleteCreditCardResult": {

"error": {},

"response": {

"BillTo.DeleteCreditCard": {

"Error": [

"No argument passed for required parameter CreditCardID”,

"Invalid argument for parameter CreditCardID. No record with this value exists in the database.”

]

}

}

}

}

Checking site settings and obtaining site data

Gathering site information - /General/GetCMSSiteOptions

This call gets the current sessions site and returns some useful general options from the site configuration in Deacom.

Parameters

  • This call takes no parameters.

Example Call

http://localhost:8181/General/GetCMSSiteOptions?SiteID=3

Example Response - Success

The below is an example of a successful call response.

{

"GetCMSSiteOptionsResult": {

"error": {},

"response": {

"General.GetCMSSiteOptions": {

"Success": {

"cs_active": true,

"cs_name": "Real Site",

"cs_allowregister": true,

"cs_cartwologin": true,

"cs_defaultdate": "Today",

"cs_userapproval": "Not Approved",

"cs_promolist": false,

"cs_productimages": false,

"cs_ordertype": "Sales Order",

"cs_minord": 10

}

}

}

}

}

Example Response - Failure

N/A - Users may receive some generic errors if site information is not returned.

Get site data - /Site/GetData

This API Endpoint will obtain the appropriate site information for the specified SiteID.

Required Paramaters

  • SiteID: relates to the dxcmssite record that the image pertains to

Optional Parameters

N/A

Example Response - Success

{

"GetDataResult": {

"error": {},

"response": {

"General.GetCMSSiteOptions": {

"response": {

"cs_active": true,

"cs_name": "Test Ecommerce",

"cs_allowregister": true,

"cs_cartwologin": true,

"cs_defaultdate": "None",

"cs_userapproval": "Not Approved",

"cs_promolist": false,

"cs_productimages": false,

"cs_ordertype": "Internet Sale",

"cs_easypost": false,

"cs_minord": 10,

"ImageIDs": "",

"PDFIDs": ""

}

}

}

}

}

Example Response - Failure

{

"GetDataResult": {

"error": {},

"response": {

"Site.GetData": {

"Error": The SiteID provided is not linked to an active site.

}

}

}

}

Get new records - /General/GetNewRecords

This call returns all new records/IDs for a given table within a particular time period. The system will return the IDs of any records which have have dxlog records created between (right now - minutes) according to dxlog.lo_date/dxlog.lo_time (ensure if going to less than 00:00 time, the previous day's results are used)

Required Parameters

  • Table - linked to dxlog.lo_table
  • Minutes - int - corresponding to number of minutes between when the call is made (Now - Minutes)

Optional Parameters

RecordID (Optional) - related to dxlog.lo_recid

Example Response - Success

{

"GetNewRecordsResult": {

"error": {},

"response": {

"General.GetNewRecords": {

"Result": {

"2151": "New Test BT"

}

}

}

}

}

Example Response - Failure

N/A - Users may receive some generic errors in the case of a failure.

Get modified records - /General/GetModifiedRecords

This call returns all modified records/IDs for the given table within a particular time period. The system will return the IDs of any records which have have dxmod records created between (right now - minutes) according to dxmod.mo_date/dxmod.mo_time (ensure if going to less than 00:00 time, the previous day's results are used). The call will also include the field name, old value, and new value when returning results. Deacom Version 16.07.065 includes the Gift Card (dmgiftcard) table to the list of possible tables that may be used with this API call.

Required Parameters

  • Table - linked to dxmod.mo_table
  • Minutes - int - corresponding to number of minutes between when the call is made (Now - Minutes)

Optional Parameters

  • RecordID (Optional) - related to dxmod.mo_recid

Example Response - Success

{

"GetModifiedRecordsResult": {

"error": {},

"response": {

"General.GetModifiedRecords": {

"Result": [

{

"ID": 929,

"Name": "Deacom, Inc. 2",

"Modifications": [

{

"Field": "bi_street",

"OldVal": "",

"NewVal": "601 Lee Rd"

},

{

"Field": "bi_city",

"OldVal": "",

"NewVal": "Chesterbrook"

},

{

"Field": "bi_state",

"OldVal": "",

"NewVal": "PA"

},

{

"Field": "bi_zip",

"OldVal": "",

"NewVal": "19087"

},

{

"Field": "bi_email",

"OldVal": "",

"NewVal": "[email protected]"

}

]

},

{

"ID": 1060,

"Name": "Matt Test 1",

"Modifications": [

{

"Field": "bi_waid",

"OldVal": "",

"NewVal": "Philadelphia"

},

{

"Field": "bi_custid",

"OldVal": "",

"NewVal": "4"

}

]

}

]

}

}

}

}

Example Response - Failure

N/A - Users may receive some generic errors in the case of a failure.

Notes on both the /General/GetNewRecords and /General/GetModifiedRecrods calls:

  • Only the following tables are currently supported by these calls: dmbill, dmship, dmprod, dmcmsuseracc
  • Records from the above tables that have had user field changes will not appear in the results as these tables have technically not had any updates. This should not be a problem, though, as the intent of the ticket is to gather any records that might be out of sync, and since eCommerce does not have dedicated UDF tables (except for storing cart UDFs) there would be nothing to require a DB sync.
  • When the Table parameter is dmprod, the results shown will only reflect parts marked as saleable within the current eCommerce site. Items that are not saleable will not be shown.
  • When the Table parameter is dmcmsuseracc, only eCommerce users tied to the current site will be shown. Additions/modifications to users belonging to another site will not be listed.
  • Check for unique records - /General/CheckForUniqueness
  • This endpoint is capable of checking for records that already exist with the chosen value in a specific table and column. Only a small subset of tables and columns are possible to check with this method, for security reasons. This call is used to check a user entry against the database before submitting data.

Example Call

http://localhost:8181/General/CheckForUniqueness?SiteID=1&Table=dmcmsuseracc&Field=cu_email&[email protected]

Syncing PDF Documents and PDF Data

Syncing PDF Documents - /Documents/GetPDF

This API Endpoint syncs PDF Documents for the appropraite items and eCommerce site.

Required Parameters

  • PdfID: relates to dmpict.pi_id
  • SiteID: relates to the dxcmssite record that the image pertains to

Optional Parameters

  • ForceBase64 - overrides the "Sync Documents To eCommerce Server" setting and returns a base64 rather than a URL no matter what.

Example Response - Success

data:application/pdf;base64, /9j/4AAQSkZJRgABAQAAAQABAAD/etc......

Example Response - Failure

Could not find any documents for the specified ID: 2190.

Syncing PDF Data - /Documents/GetPDFData

This API Endpoint syncs data within PDF Documents for the appropriate items and eCommerce site.

Required Parameters

  • PdfID: relates to dmpict.pi_id
  • SiteID: relates to the dxcmssite record that the image pertains to

Optional Parameters

N/A

Example Response - Success

{

"GetPDFDataResult": {

"error": {},

"response": {

"Documents.GetPDFData": {

"error": "",

"Success": true,

"SuccessResponse": {

"DocType": "Product",

"FrontEndURL": "",

"pi_name": "AlmondPiece1.pdf",

"pi_dcid": 11,

"pi_descrip": "",

"pi_recid": 412.0,

"pi_table": "dmprod",

"pi_id": 1

}

}

}

}

}

Example Response - Failure

{

"GetPDFDataResult": {

"error": {},

"response": {

"Documents.GetPDFData": {

"error": "Could not find any documents for the specified ID: 0.",

"Success": false,

"SuccessResponse": {}

}

}

}

}

Uploading Documents - Docuemts/UploadDocument

This API call can be used to upload documents for the front end.

Required Parameters

  • Table: Relates to pi_table
  • Record: Relates to pi_recid
  • Name: Relates to pi_name (enforce a file extension has been passed in the name)
  • Picture: Relates to pi_picture

Optional Parameters

  • Description: Relates to pi_descrip
  • DocumentCategoryName: - Relates to pi_dcid (default to system default even if not an eCommerce document category) - * this will need to search for a dmdoccat record with its dc_name = the passed and assign the doc cat id for this document to its id field value When adding the document, check if the session site has cs_syncdocs == true. If so, we also need to sync the document as the logic does in eCommerceSiteSync so that it resides in a frontend directory as well as the <ecommercedb>.dmecommpic

Example Call

http://localhost:8181/Documents/UploadDocument?Picture=thisisjustsometestdata&Table=dmecommprod&Record=25&Name=TestUpload4.png&DocumentCategoryName=General&Description=this is a test description

Example Response - Success

{

"UploadDocumentResult": {

"error": {},

"response": {

"Documents.UploadDocument": {

"error": "",

"Success": document successfully uploaded

}

}

}

}

Example Response - Failure (record ID not supplied)

Call this for error: http://localhost:8181/Documents/UploadDocument?Picture=thisisjustsometestdata&Table=dmecommprod&Name=TestUpload4.png

{

"UploadDocumentResult": {

"error": {},

"response": {

"Documents.UploadDocument": {

"error": "A record ID is required",

"Success": false

}

}

}

}

Managing Vendors

Create Vendor - /Vendors/Create

This call will add a new Vendor record in the DEACOM application.

Required Parameters

  • Any Vednor fields maked in blue in DEACOM

Optional Parameters

  • Default value fields: fields that aren’t empty on the form before user interaction
  • Fields with a whitespace default: fields that are empty on the form before user interaction

Note: This endpoint will also handle a user-specified “UniqueFields” parameter. In the case that a vendor record already exists in the db with the provided value for the respective field, the system will disallow adding a vendor with the passed arguments.

Example Call

http://localhost:8181/Vendors/Create?SiteID=1&TermID=0&ShipViaID=0&FreightID=0&CurrencyID=0&User1ID=0&User2ID=0&Facility=0&Name=Test Vendor New API 5&Phone=555-590-5777&Extension=580&Street=55 John St&Street2=Apt 401&Street3&City=New York&State=NY&County=New York County&Zip=10038&[email protected]&Fax=555-555-5555&VATID=123456789012345&TaxpayerID=1234567890&POType=Public&Active=true&AllowBackorders=true

Example Response - Success

{

"CreateResult": {

"error": {},

"response": {

"Vendors.Create": {

"Success": true,

"Result": {

"Vendor ID": 9249,

"Term ID": 25,

"Ship Via ID": 1,

"Freight ID": 1,

"Currency ID": 1,

"User 1 ID": 3,

"User 2 ID": 1,

"Facility ID": 1,

"Name": "Test Vendor New API 5",

"Phone": "555-590-5777",

"Phone Extension": "580",

"Street 1 Address": "55 John St",

"Street 2 Address": "Apt 401",

"Street 3 Address": "",

"City": "New York",

"State": "NY",

"County": "New York County",

"Zip": "10038",

"Email": "[email protected]",

"Fax": "555-555-5555",

"VAT ID": "123456789012345",

"Taxpayer ID": "1234567890",

"PO Type": "Public",

"Vendor Allows Backorders": true,

"Vendor Active State": true

}

}

}

}

}

Example Response - Failure - Non-Unique Name

{

"CreateResult": {

"error": {},

"response": {

"Vendors.Create": {

"Error": "Argument Error - There is already a Vendor object where ve_name = API Vendor Test. Please specify a unique name for this Vendor."

}

}

}

}

Obtain Vendor Data - /Vendors/GetData

This call will obtain Vendor information such as Vendor Name, Site ID, and Vendor ID.

Optional Parameters

  • SiteID- The SiteID indicates the ID number for the site. The Site ID can be obtained from the "cs_id" field on the cmssite grid.
  • Name- Vendor name
  • VendorID - The ID for the Vendor from the dmvend table

Example Call

http://localhost:8181/Vendors/GetData?SiteID=1&VendorID=9244&Name=API Vendor Test

Example Response - Success

{

"GetDataResult": {

"error": {},

"response": {

"Vendors.GetData": {

"UserFields": {

"9244": {}

},

"Success": true,

"Result": {

"Vendor 1": {

"ve_id": 9244,

"ve_teid": 1,

"ve_trid": 1,

"ve_frid": 1,

"ve_fcid": 1,

"ve_p1id": 1,

"ve_p2id": 1,

"ve_name": "API Vendor Test",

"ve_phone": "555-590-5777",

"ve_phext": "580",

"ve_street": "55 John St",

"ve_street2": "Apt 401",

"ve_street3": "",

"ve_city": "New York",

"ve_state": "NY",

"ve_county": "New York County",

"ve_zip": "10038",

"ve_email": "[email protected]",

"ve_fax": "555-555-5555",

"ve_vatid": "123456789012345",

"ve_taxid": "1234567890",

"ve_potype": "Public",

"ve_backord": true,

"ve_active": true,

"ImageIDs": "0",

"PDFIDs": "0"

}

}

}

}

}

}

Example Response - Failure

N/A

Managing Deals and Commissions

These API calls can be used to create, update, and obtain reletive data for Deals and Sales Commissions in the DEACOM eCommerce application.

Create Commissions - /Commissions/Create

Parameters

  • Description, c2_descrip, required string (passed: sm_lname)
  • CompanyType: c2_comptype, option string (default: "All Bill-To Companies)
  • For: c2_for, required string (pass: "Salesman")
  • Recid: c2_fornum, required int (pass: sm_id)
  • On: c2_on, optional string (default "All Items)
  • Type: c2_type, optional string (default: "Dollars per Unit")
  • Factor: c2_typenum, required decimal (pass: webstore profit amount)
  • CommissionDate: c2_paytype, optional string (default: "Pay Date")
  • DateBasedOn: c2_basedon, optional string (Default: "Created")
  • StartDate: c2_start, optional datetime (Default: Today/now)
  • EndDate: c2_end, optional datemtime (Default: 12/29/2099)
  • Active: c2_active, optional boolean (default true)
  • IncludFreightCost: c2_includeFreight, optional boolean (default true)

Example Call

http://localhost:8181/Commissions/Create?SiteID=1&Description=SalesmanLastName&For=Salesman&ForName=010 Nich Sachs&Recid=1&CompanyType=All Bill-To Companies&On=All Items&Type=Dollars Per Unit&Factor=5&Minimum=0&StartDate=1/1/2021&EndDate=1/1/2099&Active=false&IncludeFreightCost=false&CommissionDate=Pay Date&DateBasedOn=Created

Example Response - Success

{

"CreateResult": {

"error": {},

"response": {

"Commissions.Create": {

"Success": true,

"Result": {

"Commission ID": 2030,

"Description": "SalesmanLastName",

"For ID": 1,

"For Type": "Salesman",

"For Name": "010 Nich Sachs",

"Company Type": "All Bill-To Companies",

"On Type": "All Items",

"On Name": "All Items",

"Payment Type": "Pay Date",

"Date Based On": "Created",

"Commission Type": "Dollars Per Unit",

"Commission Factor": 5,

"Commission Start Date": "2021-01-01T00:00:00",

"Commission End Date": "2099-01-01T00:00:00",

"Commission Active State": false,

"Include Freight Cost": false

}

}

}

}

}

Example Response - Failure

N/A

Update Commissions - /Commissions/Update

Parameters

  • ID- required, deal id
  • Newvalues - be able to handle all fields specified in Deals/Create

Example Call

http://localhost:8181/Commissions/Update?SiteID=1&CommissionID=2029&NewValues=[{'c2_descrip':'test abc'},{'c2_for':'asdf'},{'c2_fornum':'9'},{'c2_forname':'bup'},{'c2_typenum':'2'},{'c2_comptype':'111a111'},{'c2_on':'bup1'},{'c2_onname':'bup2'},{'c2_type':'bup3'},{'c2_paytype':'bup4'},{'c2_basedon':'bup5'},{'c2_start':'2/28/2019'},{'c2_end':'12/12/2029'},{'c2_active':'true'},{'c2_includefreight':'true'}]

Example Response - Success

{

"UpdateResult": {

"error": {},

"response": {

"Commissions.Update": {

"Success": true,

"Result": "Update succeeded"

}

}

}

}

Example Response - Failure

N/A

Get Commissions Data - /Commissions/GetData

Parameters

  • DealID, required, de_id

Example Call

http://localhost:8181/Commissions/GetData?SiteID=1&CommissionID=2029

Example Response - Sucess

{

"GetDataResult": {

"error": {},

"response": {

"Commissions.GetData": {

"Success": true,

"Result": {

"c2_id": 2027,

"c2_descrip": "SalesmanLastName",

"c2_fornum": 1,

"c2_for": "Salesman",

"c2_forname": "010 Nich Sachs",

"c2_typenum": 5,

"c2_comptype": "All Bill-To Companies",

"c2_on": "All Items",

"c2_onname": "All Items",

"c2_type": "Dollars Per Unit",

"c2_paytype": "Pay Date",

"c2_basedon": "Created",

"c2_start": "2021-01-01T00:00:00",

"c2_end": "2099-01-01T00:00:00",

"c2_active": false,

"c2_includefreight": false,

"ImageIDs": "0",

"PDFIDs": "0" },

"UserFields": {"2027": {}

}

}

}

}

}

Example Response - Failure

NA

Create Deals - Deals/Create

Parameters

  • Description: de_descrip required string (pass: sm_lname)
  • For: de_for, required string (pass: "Salesman")
  • Recid: de_fornum, required int (pass: sm_id)
  • On: de_on, optional string (default: "All Items")
  • Type: de_type, optional string (default: "List Menus %")
  • Factor: de_typenum, required decimal (pass: webstore percentage)
  • Minimum: de_minimum, optional decimal (default: 0.00)
  • StartDate: de_start, optional datetime (default today/now)
  • EndDate: de_end, optional datetime (default 12/29/2099)
  • Active: de_active, optional boolean (default true)

Example Call

http://localhost:8181/Deals/Create?SiteID=1&Description=A test deal for the API&For=Salesman&ForName=FUNDRAISER&Recid=1&On=All Items&Type=List Minus %&Factor=10&Minimum=0&StartDate=1/1/2021&EndDate=1/1/2099&Active=true

Example Response - Success

{

"CreateResult": {

"error": {},

"response": {

"Deals.Create": {

"Success": true,

"Result": {

"Deal ID": 2740,

"Description": "A test deal for the API",

"For ID": 1,

"For Type": "Salesman",

"For Name": "FUNDRAISER",

"On Type": "All Items",

"On Name": "All Items",

"Deal Type": "List Minus %",

"Deal Factor": 10,

"Deal Minimum": 0,

"Deal Start Date": "2021-01-01T00:00:00",

"Deal End Date": "2099-01-01T00:00:00",

"Deal Active State": true

}

}

}

}

}

Example Response - Failure

N/A

Update Deals - Deals/Update

Parameters

  • ID- required, deal id
  • Newvalues - be able to handle all fields specified in /Deals/Create

Example Call

localhost:8181/Deals/Update?SiteID=1&DealID=2738&NewValues=[{'de_descrip':'test1'},{'de_fornum':'5'},{'de_for':'test2'},{'de_forname':'test3'},{'de_on':'test4'},{'de_onname':'test5'},{'de_type':'test6'},{'de_typenum':'3'},{'de_start':'12/2/2009'},{'de_active':'false'}]

Example Response - Success

{

"UpdateResult": {

"error": {},

"response": {

"Deals.Update": {

"Success": true,

"Result": "Update succeeded"

}

}

}

}

Example Response - Failure

N/A

Get Deals Data - Deals/GetData

Parameters

  • DealID, required, de_id - Returns the DealsModel specified

Example Call

localhost:8181/Deals/GetData?SiteID=1&DealID=2738

Example Response - Success

{

"GetDataResult": {

"error": {},

"response": {

"Deals.GetData": {

"Success": true,

"Result": {

"de_id": 2740,

"de_descrip": "A test deal for the API",

"de_fornum": 1,

"de_for": "Salesman",

"de_forname": "FUNDRAISER",

"de_on": "All Items",

"de_onname": "All Items",

"de_type": "List Minus %",

"de_typenum": 10,

"de_minimum": 0,

"de_start": "2021-01-01T00:00:00",

"de_end": "2099-01-01T00:00:00",

"de_active": true,

"ImageIDs": "0",

"PDFIDs": "0" },

"UserFields": {"2740": {}

}

}

}

}

}

Example Response - Failure

N/A

Stateless Endpoints

Note: - These endpoints are only applied when the "Stateless API Only" box on the Edit ECommerce User form is checked.

Get Multiple Order - /Order/StatelessGetMultiple

This API call will retrieve sales order details for a single sales order or multiple sales orders, given the specific filters chosen. Note: Beginning in version 16.07.058, the UDF data for the Sales Order Header and each Sales Order Line is now displayed in the returned JSON.

Required Parameters

  • OrderedStartDate - related to to_ordered

Optional Parameters

  • OrderedEndDate - related to to_ordered
  • Facility - related to to_waid
  • BillToID - related to to_biid
  • ShipToID - related to to_shid
  • OrderNumber - related to to_ordnum
  • MasterOrderNumber - related to to_masterordnum
  • Additional Fields - a comma-separated list of field names used to specify any additional fields that should be returned in the response of this function. Any fields that can be added as a grid column in the main app Sales Order Detail grid can be specified here to be returned, including user fields. Note: all Header UDFs and Line UDFs are returned under a singular response object.
  • ModifiedStartDate - corresponds to "to_recdate".
  • ModifiedEndDate - corresponds to "to_recdate".
  • ModifiedStartDateTime - corresponds to "to_recdate"
  • ModifiedEndDateTime - corresponds to "to_recdate"

Notes:

  • (Usage of "ModifiedStartDate" or "ModifiedEndDate" has been disallowed at the same time as the usage of "OrderedStartDate" or "OrderedEndDate".)
  • The ModifiedStartDateTime and ModifiedEndDateTime parameters can filter down to the second, and will be provided using 24hr time. Example 13:15:48.
  • When a start date time is supplied
  • ModifiedStartDate is required, throw a prompt if both aren't supplied.
  • Filter on both the start date and time so orders equal to or after the start date and time are returned
  • When an end date time is supplied
  • ModifiedEndDate is required, throw a prompt if both aren't supplied
  • Filter on both the end date and time so orders equal to or before the end date and time are returned.
  • A time should be able to be able to be supplied for one date and not the other.
  • When using the "ModifiedStartDate" parameter, the call will check whether a dxmod record has been posted against the Sales Orders. If a modification was posted against the order within the designated time frame, the Sales Order will be allowed to return in the response JSON.

Example Call

http://localhost:8181/Order/StatelessGetMultiple?SiteID=1&OrderedStartDate=6/01/2022&OrderedEndDate=6/30/2022&ShipToIDs=2812, 2813&BillToIDs=2235, 2236

Example Response - Success

The below is an example of a successful call response.

{

"StatelessGetMultipleResult": {

"error": {},

"respose": {

"Order.StatelessGetMultiple": {

"Success": true,

"Orders": [

{

"bi_name": "GIAQUITA",

"or_exten": 28.75,

"or_ordquant": 1,

"or_price": 28.75,

"or_prid": 2775,

"or_shipquant": 0,

"pr_codenum": "1M100AD",

"sh_name": "MUMM",

"to_balance": 29.71,

"to_biid": 2235,

"to_cofirmn": "",

"to_dueship": "02/01/2024",

"to_masterordnum": 2022114380600,

"to_orddate": "06/30/2022",

"to_ordered": "06/30/2022",

"to_ordnum": 2022114380800,

"to_condate": "06/30/2022",

"to_ordtype": "s",

"to_paydate": "",

"to_recdate": "06/30/2022",

"to_saved": "06/30/2022",

"to_shid": 2813,

"to_shipped": "",

"to_totdue": 29.71,

"to_waid": 1,

"tr_name1": "FedEx Groud"

},

{

"bi_name": "GIAQUITA",

"or_exten": 0.96,

"or_ordquant": 1,

"or_price": 0.96,

"or_prid": 0,

"or_shipquant": 0,

"pr_codenum": "",

"sh_name": "MUMM",

"to_balance": 29.71,

"to_biid": 2235,

"to_cofirmn": "",

"to_dueship": "02/01/2024",

"to_masterordnum": 2022114380600,

"to_orddate": "06/30/2022",

"to_ordered": "06/30/2022",

"to_ordnum": 2022114380800,

"to_ordtype": "s",

"to_paydate": "",

"to_recdate": "06/30/2022",

"to_saved": "06/30/2022",

"to_shid": 2813,

"to_shipped": "",

"to_totdue": 29.71,

"to_waid": 1,

"tr_name1": "FedEx Groud"

},

{

"bi_name": "GIAQUITA",

"or_exten": 53.5,

"or_ordquant": 2,

"or_price": 26.75,

"or_prid": 2774,

"or_shipquant": 0,

"pr_codenum": "1M100",

"sh_name": "DRISCOLL",

"to_balance": 56.1,

"to_biid": 2235,

"to_cofirmn": "",

"to_dueship": "02/01/2024",

"to_masterordnum": 2022114380600,

"to_orddate": "06/30/2022",

"to_ordered": "06/30/2022",

"to_ordnum": 2022114380700,

"to_ordtype": "s",

"to_paydate": "",

"to_recdate": "06/30/2022",

"to_saved": "06/30/2022",

"to_shid": 2812,

"to_shipped": "",

"to_totdue": 56.1,

"to_waid": 1,

"tr_name1": "FedEx Groud"

}

]

}

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of no results found.

{

"StatelessGetMultipleResult": {

"error": {},

"response": {

"Order.StatelessGetMultiple": {

"Error": "Argument Error - Could not find any orders matching the specified parameters.

}

]

}

}

}

}

Return a breakdown of all available item discounts - /Item/StatelessGetPricingMatrix

This endpoint shows a breakdown of all available discounts for a given item at various quantities (Along with accompanying details about that discount).

Parameters

  • PartID - Deacom part number
  • BillToID - Deacom Bill-To customer
  • ShipToID - Deacom Bill-To customer

Example Call

http://localhost:8181/Item/StatelessGetPricingMatrix?SiteID=1&PartID=2774&BillToID=224241&ShipToID=1308231

Example Response - Success

The below is an example of a successful call response.

{

"StatelessGetPricingMatrixResult": {

"error": {},

"response": {

"Item.StatelessGetPricingMatrix": {

"Result": {

"Price_1": {

"Base_Prices": {

"Price_Per_Sales_Unit": 26.75,

"Price_Per_Container": 26.75,

"Price_Extended": 26.75

},

"General_Info": {

"Pricing_Source": "Item Master List Price",

"Quantity_Threshold": 1,

"Sales_Unit_Factor": 1

},

"Price_2": {

"Base_Prices": {

"Price_Per_Sales_Unit": 21.4,

"Price_Per_Container": 21.4,

"Price_Extended": 107

},

"General_Info": {

"Pricing_Source": "Promotion",

"Quantity_Threshold": 5,

"Sales_Unit_Factor": 1

},

"Promo_Info": {

"Promo_1": {

"Promotional_Price_Per_Sales_Unit": 21.4,

"Promotional_Price_Per_Container": 21.4,

"Promotional_Price_Extended": 107,

"Promo_ID": 4,

"Promo_Name": "20 Percent Off Order",

"Promo_For": "Specific Bill to Company",

"Promo_For_Name": "All Bill to Companies",

"Promo_Type": "Percent off",

"Promo_Factor": 20,

"Promo_Expiration_Date": "2099-02-27T00:00:00",

"Promo_Quantity_Threshold": 5,

"Promo_Minimum_Quantity_Basis": "Ordered",

"Promo_Applied_Time": "Ordered"

}

}

},

Example Response - Failure

The below is an example of a failed call response, as a result of required parameters missing.

{

"StatelessGetPricingMatrixResult": {

"error": {},

"response": {

"Item.StatelessGetPricingMatrix": {

"Error": "Argument Error - The [BillToID] and [ShipToID] parameters must be passed, and must be nonzero."

}

]

}

}

}

},

Creating a Bill-To record - /BillTo/StatelessCreate

When called, this API will create a new Bill-To for the passed in criteria, and link the new Bill-to to the Ship-To or User, when provided. A success message and the Bill-To ID will be returned upon a successful call. Beginning in version 16.07.116, this API call has been converted from a GET request to a POST request.

Parameters

  • Name - the Bill-To name
  • Street (optional) - the Bill-To street
  • Street2 (optional) - the Bill-To street (cont'd)
  • Street3 (optional) - the Bill-To street (cont'd)
  • City (optional) - the Bill-To city
  • State (optional) - the Bill-To state
  • Zip (optional) - the Bill-To zip code
  • Phone (optional) - the Bill-To phone
  • Country (optional) - the Bill-To country
  • ShipToID (optional) - the Ship-To ID to link to
  • UserID (optional) - the User ID to link to
  • DBA (optional) - the entry in the DBA (Doing Business As) field
  • Contact (optional) - the Contact listed on the Bill-to record
  • Dear (optional) - The name of the person in the Dear field (bi_dear) of the Bill-To record in DEACOM.
  • CurrencyID - available beginning in version 17.01.053, this parameter that allows a currency to be assigned on the new object. See the eCommerce and Foreign Currency section at the top of the page for more details.

Notes:

  • The following fields are copied from the Bill To Company specified on the Customer Defaults tab via Tools > Maintenance > eCommerce Sites. when using the BillTo/Create API call: dmbill.bi_c3id, dmbill.bi_pastday, dmbill.bi_exday, dmbill.bi_creddueshipdays, dmbill.bi_credlim, dmbill.bi_exceed, dmbill.bi_credflag.
  • Beginning in version 16.07.058, a JSON array of UDF data can be passed into the new "UserFieldValues" parameter. This will set the chosen User Fields on the Bill-To that is being modified.

Example Call

http://localhost:8181/BillTo/StatelessCreate?SiteID=1&Name=Ryan Test 2&Street=55 John St&Street2=APT 3D&Street3&City=New York&State=New York&Zip=10038&Phone=5555555555&[email protected]&Country=USA&ShipToID&UserID=2&Contact=Ryan OHara&DBA=Ry&Dear=Ryan

Example Response - Success

The below is an example of a successful call response.

{

"StatelessCreateResult": {

"error": {},

"response": {

"BillTo.StatelessCreate": {

"Success": true,

"bi_id": 224245

}

}

}

}

},

Example Response - Failure

The below is an example of a failed call response, as a result of required parameter missing.

{

"StatelessCreateResult": {

"error": {},

"response": {

"BillTo.StatelessCreate": {

"Error": "You must provide a Bill-To name."

}

}

}

}

},

Obtaining Bill-to information - /BillTo/StatelessGetData

This function has no parameters. It will identify the Bill-To ID linked to the currently logged in user (or linked to the cart if no user is logged in) and will return all dmbill fields and dmbill user fields for that Bill-To.

Parameters:

  • CartBillToID - Optional. The id of the cart for the selected Bill-to
  • Email - Optional. The bi_email value for the Bill-To record. If this Email paramater is used, the syestem will match on the bi_email instead of the bi_id check and return all bill-tos that have this email (case insensitive, trimmed comparison)

Notes:

  • Beginning in version 16.07.058 any User Field data on the object will automatically be displayed in the returned JSON when running this API.
  • Beginning in version 16.07.072 the related Ship-To IDs for the Bill-To will be returned in the call.

Example Call

http://localhost:8181/BillTo/StatelessGetData?SiteID=1&CurrencyID=1&BillToIDs=224244, 224240

Example Response - Success

The below is an example of a successful call response.

{

"StatelessGetDataResult": {

"error": {},

"response": {

"BillTo.StatelessGetData": {

"bi_id": 224240,

"bi_name": "Ryan Test",

"bi_active": true,

"bi_street": "55 John St",

"bi_street2": "APT 3D",

"bi_street3": "",

"bi_city": "New York",

"bi_state": "New York",

"bi_zip": "10038",

"bi_phone": "5555555555",

"bi_fax": "",

"bi_contact": "Ryan OHara",

"bi_country": "USA",

"bi_phext": "",

"bi_email": "[email protected]",

"bi_poreqd": false,

"bi_credhld": null,

"bi_credflag": false,

"bi_reqcpart": false,

"bi_grid": 1,

"bi_dba": "Ry",

"bi_dear": "Ryan",

},

{

"bi_id": 224244,

"bi_name": "Ryan Test 2",

"bi_active": true,

"bi_street": "55 John St",

"bi_street2": "APT 3D",

"bi_city": "New York",

"bi_state": "New York",

"bi_zip": "10038",

"bi_phone": "1231231234",

"bi_fax": "",

"bi_contact": "Ryan OHara",

"bi_country": "USA",

"bi_phext": "",

"bi_email": "[email protected]",

"bi_poreqd": false,

"bi_credhld": null,

"bi_credflag": false,

"bi_reqcpart": false,

"bi_grid": 1,

"bi_dba": "test dba name",

"bi_dear": "Ryan"

},

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of required parameter missing.

{

"StatelessGetDataResult": {

"error": {},

"response": {

"BillTo.StatelessGetData": {

"Error": "Argument Error - The [BillToIDs] parameter is required, but no arguments were specified."

}

}

}

}

}

Modifying a Bill-To record - /BillTo/StatelessUpdate

This function call updates a Bill-to record based on the new values passed in. The Bill-to record to be updated is determined by the default Bill-to on the current session's user, or the current session's cart if no user is logged in. The following fields can currently be set by this function: bi_name, bi_street, bi_street2, bi_street3, bi_city, bi_state, bi_zip, bi_phone, bi_fax, bi_email, bi_contact, bi_country, bi_phext, bi_active, bi_poreqd, bi_credflg, bi_reqcpart, bi_credhld, bi_grid, bi_said, bi_dba, and all dmbill user fields. Beginning in version 16.07.116, this API call has been converted from a GET request to a POST request.

Parameters

  • New Values - A string containing the lookup of fields and new values to set. Example: [{"bi_name":"eCommerce Test - Name"}, {"bi_street":"601 Lee Rd"},{"bi_active":"true"}, {"bi_credhld":"02/20/2019"}, {"bi_dba":"dba test"}]
  • UserFieldValues(optional) - A string containing the lookup of user field IDs (d1_id) and values to set. Example: [{"54":"eCommerce Test"}, {"73":"True"},{"242":"Test2"}]
  • UpdateEcommUser(optional) - A boolean value. When true, the email address or phone number of the current user will also be updated, in addition to updating these fields on the Bill-To.
  • Dear (optional) - The name of the person in the Dear field (bi_dear) of the Bill-To record in DEACOM.
  • RecordID(optional) - The RecordID parameter must match the cart's Bill-To or the user's Bill-To.

Note: Beginning in version 16.07.058, a JSON array of UDF data can be passed into the new "UserFieldValues" parameter. This will set the chosen User Fields on the Bill-To that is being modified.

Example Call

http://localhost:8181/BillTo/StatelessUpdate?SiteID=1&NewValues=[{'224244':\"[{'bi_phone':'5555555555'},{'bi_city':'New York'}]\"}, {'2235':\"[{'bi_phone':'4546768998'},{'bi_city':'New York'}]\"}, {'777':\"[{'bi_phone':'1234567890'},{'bi_city':'Chicago'}]\"}]"

Example Response - Success

The below is an example of a successful call response.

{

"StatelessUpdateResult": {

"error": {},

"response": {

"BillTo.StatelessUpdate\": {

"Success": true,

"Result": {

"777": "Update successful",

"2235: "Update successful",

"224244": "Update successful"

}

}

}

}

},

Example Response - Partial Success

{

"StatelessUpdateResult": {

"error": {},

"response": {

"BillTo.StatelessUpdate": {

"Success": false,

"Message": "Some Bill-To Companies were unable to be updated. Please check the [Result] node for further details.",

"Result": {

"777": "Update successful",

"22535": "Update successful",

"224244554": "Error: Could not find a valid Bill-To company for ID [224244554]."

}

}

}

}

},

Example Response - Failure

The below is an example of a failed call response, as a result of required parameter missing.

{

"StatelessUpdateResult": {

"error": {},

"response": {

"BillTo.StatelessUpdate": {

"Error": "Argument Error - The [NewValues] parameter is required, but was not specified"

}

}

}

},

Creating a Ship-To record - /ShipTo/StatelessCreate

This call is used to create a new Ship-to record with the parameters specified and link it to the Bill-to (if specified).

Parameters

If either of the below parameters are provided, a link will be created between the Ship-to that gets created and the Bill-to customer specified (dmbillship).

  • Name - the name of the Ship-to Company
  • Street, Street2, Street3, CIty, State, Zip (optional) - the shipping address information for the Ship-to Company.
  • Phone, Email (optional) - the contact information for the Ship-to Company
  • BillToID (optional) - the Bill-to ID to link to.
  • UserID (optional) - the User ID to get the Bill-to ID from.
  • Country (optional) - the country of the Ship-to address.
  • DBA (optional) - the entry in the DBA (Doing Business As) field
  • Contact (optional) - the Contact listed on the Ship-to record
  • Dear (optional) - the name of the person in the Dear field (sh_dear) of the Ship-To record in DEACOM.
  • ServiceType(optional) - the service type (sh_svctype) of the Ship-To Company. Options are "None", "Business", "Mixed", "Residential", "Unknown"
  • AddressValidated(optional) - date field - specifies the date (sh_addressvalid) the address was last validated.
  • Fax(optional) - the fax number from the Ship-To company in Deacom. Corresponds to the "sh_fax" database field when saving the resulting Ship-To entry.
  • CurrencyID - available beginning in version 17.01.053, this parameter that allows a currency to be assigned on the new object. See the eCommerce and Foreign Currency section at the top of the page for more details.

Note: Beginning in version 16.07.058, a JSON array of UDF data can be passed into the new "UserFieldValues" parameter. This will set the chosen User Fields on the Ship-To that is being modified.

Example Call

http://localhost:8181/ShipTo/StatelessCreate?SiteID=1&Name=Ryan Test Ship 2&Street=55 John St&Street2=APT 3D&City=New York&State=New York&Zip=10038&Phone=5555555555&[email protected]&Country=USA&Contact=Ryan OHara&DBA=Ry&Dear=Ryan&DefaultShipTo=true

Example Response - Success

The below is an example of a successful call response.

{

"StatelessCreateResult": {

"error": {},

"response": {

"ShipTo.StatelessCreate": {

"Success": true,

"sh_id": 1308233

}

}

}

}

},

Example Response - Failure

The below is an example of a failed call response, as a result of required parameter missing.

{

"StatelessCreateResult": {

"error": {},

"response": {

"ShipTo.StatelessCreate": {

"Error": "You must provide a Ship-To name."

}

}

}

}

},

Obtaining Ship-to information - /ShipTo/StatelessGetData

This function has no parameters. It will identify the Ship-To ID linked to the currently logged in user (or linked to the cart if no user is logged in) and will return all dmship fields and dmship user fields for that Ship-To.

Parameters:

CartShipToID - Optional. The id of the cart for the selected Ship-to

Notes:

  • Beginning in version 16.07.058 any User Field data on the object will automatically be displayed in the returned JSON when running this API.
  • Beginning in version 16.07.072 the related Bill-To IDs for the Ship-To will be returned in the call.

Example Call

http://localhost:8181/ShipTo/StatelessGetData?SiteID=1&ShipToIDs=1308232, 1308220, 1308221

Example Response - Success

The below is an example of a successful call response.

{

"StatelessGetDataResult": {

"error": {},

"response": {

"ShipTo.StatelessGetData": {

"sh_id": 1308220,

"sh_name": "Ryan Test",

"sh_street": "55 John St",

"sh_street2": "APT 3D",

"sh_street3": "",

"sh_active": true,

"sh_trid": 7,

"sh_city": "New York",

"sh_state": "New York",

"sh_zip": "10038",

"sh_phone": "5555555555",

"sh_fax": "",

"sh_credhld": null,

"sh_credflag": false,

"sh_contact": "Ryan OHara",

"sh_country": "USA",

"sh_phext": "",

"sh_email": "[email protected]",

"sh_reqcpart": false,

"sh_waid": 1,

"sh_brid": 1,

"sh_dba": "Ry",

"sh_dear": "Ryan",

"sh_svctype": "",

"sh_addressvalid": null,

"sh_default": false,

"sh_teid": 1,

"sh_s1id": 5,

"sh_s2id": 1,

"sh_s3id": 1,

"sh_s4id": 1,

"sh_s5id": 1

},

"sh_id": 1308232,

"sh_name": "Ryan Test Ship 2",

"sh_street": "55 John St",

"sh_street2": "APT 3D",

"sh_active": true,

"sh_trid": 7,

"sh_city": "New York",

"sh_state": "New York",

"sh_zip": "10038",

"sh_phone": "5555555555",

"sh_fax": "",

"sh_credhld": null,

"sh_credflag": false,

"sh_contact": "Ryan OHara",

"sh_country": "USA",

"sh_phext": "",

"sh_email": "[email protected]",

"sh_reqcpart": false,

"sh_waid": 1,

"sh_brid": 1,

"sh_dba": "Ry",

"sh_dear": "Ryan",

"sh_svctype": "",

"sh_addressvalid": null,

"sh_default": false,

"sh_teid": 1,

"sh_s1id": 5,

"sh_s2id": 1,

"sh_s3id": 1,

"sh_s4id": 1,

"sh_s5id": 1

},

}

}

}

Example Response - Failure

The below is an example of a failed call response, as a result of required parameter missing.

{

"StatelessGetDataResult": {

"error": {},

"response": {

"ShipTo.StatelessGetData": {

"Error": "Argument Error - The [ShipToIDs] parameter is required, but no arguments were specified."

}

}

}

}

}

Modifying a Ship-To record - /ShipTo/StatelessUpdate

This function call updates a Ship-to record based on new values passed in. The Ship-to record to be updated is determined by the default Ship-to on the current session's user, or the current session's cart if no user is logged in. The following fields can currently be set by this function: sh_name, sh_street, sh_street2, sh_street3, sh_city, sh_state, sh_phone, sh_fax, sh_email, sh_contact, sh_country, sh_phext, sh_active, sh_poreqd, sh_credflg, sh_reqcpart, sh_credhld, sh_said, sh_dba, sh_svctype, sh_addressvalid, and all dmship user fields. Beginning in version 16.07.116, this API call has been converted from a GET request to a POST request.

Parameters

  • NewValues - A string containing the lookup of fields and new values to set. Example: [{"sh_name":"eCommerce Test - Name"}, {"sh_street":"601 Lee Rd"},{"sh_active":"true"}, {"sh_credhld":"02/20/2019"}, {"sh_dba":"dba test"},{"sh_svctype":"Business"},{"sh_addressvalid":"02/07/2020"}]
  • UserFieldValues (optional) - A string containing the lookup of user field IDs (d1_id) and values to set. Example: [{"57":"eCommerce Test"}, {"60":"100"},{"229":"Test2"}]
  • Dear (optional) - The name of the person in the Dear field (sh_dear) of the Ship-To record in DEACOM.
  • RecordID(optional) - The RecordID parameter must match one of the following: The cart's Ship-To, the user's Ship-To, a Ship-To linked to the current user's Bill-To (anything returned by User/GetShipTo), or a Ship-To that is currently set on a cart line item.

Note: Beginning in version 16.07.058, a JSON array of UDF data can be passed into the new "UserFieldValues" parameter. This will set the chosen User Fields on the Ship-To that is being modified.

Example Call

http://localhost:8181/ShipTo/StatelessUpdate?SiteID=1&NewValues=[{'1308232':\"[{'sh_street':'1088 Test St'},{'sh_city':'Fake City'}]\"

Example Response - Success

The below is an example of a successful call response.

{

"StatelessUpdateResult": {

"error": {},

"response": {

"ShipTo.StatelessUpdate\": {

"Success": true,

"Result": {

"1308220": "Update successful",

"1308221": "Update successful",

"1308232": "Update successful"

}

}

}

}

},

Example Response - Partial Success

{

"StatelessUpdateResult": {

"error": {},

"response": {

"ShipTo.StatelessUpdate": {

"Success": false,

"Message": "Some Ship-To Companies were unable to be updated. Please check the [Result] node for further details.",

"Result": {

"1308221": "Update successful",

"1308232": "Update successful",

"13089220": "Error: Could not find a valid Bill-To company for ID [13089220]."

}

}

}

}

},

Example Response - Failure

The below is an example of a failed call response, as a result of required parameter missing.

{

"StatelessUpdateResult": {

"error": {},

"response": {

"ShipTo.StatelessUpdate": {

"Error": "Argument Error - The [NewValues] parameter is required, but was not specified"

}

}

}

},