Parameter Settings > Point of Sale > Ecommerce Tab

The ecommerce API and the ecommerce tools in the application allow you to sell your products to your customers (consumers and accounts) online and process those orders and quotes using the import function in Point of Sale. You can also process an account's payments submitted online. The instructions on this page are the same for both the Spruce and RockSolid MAX applications. To complete the setup process, you must have administrative permissions to the application. This section explains the parameter settings for ecommerce imports only. For a comprehensive understanding of all of the required ecommerce set up, see the Special Topic on Ecommerce.

Note: The Spruce eCommerce-specific settings give businesses access to both the Ecommerce API and EvolutionX-based methods and features.

A Note about Cloud Hosted and On Prem API Updates

When we upgrade the application in the Hosted environment, the application contains the new code to support the new API by default. On-prem systems rely on an automated process that is triggered nightly by the Spruce services running on their SQL server, which checks for, downloads, and installs updates to the SpruceWeb web service. This on-premise process is not always reliable, due to local environmental settings (including Servers and Network infrastructure), which can result in the SpruceWeb web service not being updated to the latest release.

Completing the Ecommerce Parameter Settings

Use the options in this tab to setup the adjustment codes, tax settings, default SKUs, bankcard types, and notification settings required to support the use of an API (Application Programming Interface) in processing incoming orders, quotes, and account payments. You can also specify confirmation email settings, define how to apply online account payments, and specify how online orders are managed using the parameters in this tab. After you save these settings, much of the ecommerce process runs as you have directed here.

The settings for Spruce eCommerce are slightly different than for businesses that use the Ecommerce API only. See the Spruce eCommerce topic here for more information.

ECI Support team members can help you set up the background options for your custom ecommerce website, but these settings you can complete on your own.

To set up the ecommerce parameters:

1. From the Main Menu, choose Maintenance > Database > Parameters to display the Parameter Settings form.

2. Choose the Point of Sale tab and the Ecommerce  subtab to display the ecommerce settings.

3. Complete these ecommerce setup options to manage incoming orders and quotes:

  • Delivery Adder
    This adjustment code is used to either set or calculate the delivery charge for online orders. When you create the delivery adder code, it appears in this list.
    For assistance in setting up this adjustment, see Setting up the Delivery Charge Adder Code.

  • Delivery Discount Adder
    This adjustment code is used to either set or calculate the discount for the delivery charge, if applicable. When you create this discount code, it appears in this list.
    For assistance in setting up this adjustments, see Setting up the Delivery Discount Adjustment Code.

  • Discount Adder
    This adjustment code is used to apply a discount to an ecommerce order. It is not required. When you create a discount adder of any type, it appears in this list. For assistance in setting up this adjustment, see Setting up the Discount Adjustment Code.

  • Tax Code
    Default tax code that is used to calculate the online order or quote's tax amount if there is no local tax amount applied in the response. When you create this tax code, it appears in this list. For assistance in setting up this code, see Setting up the Default Tax Code. This entry is not used for Spruce eCommerce tax processing.
    Note: This tax code parameter may require a different tax percentage than is used in the master branch. We recommend you follow local and regional tax guidelines to define this calculation.

  • Bankcard Type
    The bankcard type helps keep the incoming amounts separate from the store income. This is important for tax purposes. For assistance in setting up this card type, see Setting up the Ecommerce Bank Card Type.

  • Totals Code
    When there is a discrepancy between the amount that is calculated during the online transaction and what the application calculates, the system uses the Totals code to manage the difference. Discrepancies usually have to do with tax and deposit differences or issues that occur during the import process. For assistance in setting up this code type, see Setting up the Totals Code.

  • Notify User or Group
    After you train your staff how to import and process online orders, quotes, and payments, the system needs to be able to notify them when an online transaction arrives. This entry represents either the user ID of the person who is handling these transactions or the group of users who are notified when a transaction is submitted. For assistance in completing notification settings, see Setting up a User/Group for API Orders and Quotes Notification.

4. When you receive online orders and payments, you can let your account customers know that you have processed them via email using these settings.

  • Online Orders
    Choose this check box to notify the customer (using their submitted email address) that you have received their online order. Leave this check box unselected if you use Spruce eCommerce for ecommerce processing.

  • Online Payments
    Choose this check box to notify the customer (using their submitted email address) that you have processed their online payment. Leave this check box unselected if you use Spruce eCommerce for ecommerce processing.

5. To process payments automatically, select this check box:

  • Auto Post Online Payments
    Select this check box to post ecommerce customer-submitted payments to the specified account.

6. To set the Online Orders options, select the check boxes below to apply specific settings to incoming online orders:

  • Allow cash account with $0 deposit orders
    Enable this check box when the business allows customers to purchase items online without paying a deposit.
    Note: If the parameter is enabled, the payment bypasses the $0 payment validation processes. If the parameter is not enabled, the method uses the current validation process according to the account type and Card on File properties set for the account. This option is not required for Spruce eCommerce sites.

  • Enforce PO Number Requirement
    For accounts that have the Require PO setting enabled in Account Maintenance, selecting this check box ensures that each incoming online order has a Purchase Order number assigned to it. When you select this option, incoming ecommerce orders associated with these accounts that do not have a PO Number will result in an error.

  • Allow zero price on items

    Select this check box to allow incoming online order items to have a price of zero. This option can be applied to Spruce eCommerce sites.

  • Enforce credit limits
    Enable this check box to prevent existing accounts from going over their established credit limit amount (auto-processed orders only). This check box is not selected by default. Orders that are not processed automatically will not consider the account’s credit limit.

    Note: If this option is checked and the order goes over the account’s credit limit, the application queues the order rather than remove it.

7. If you are using Spruce eCommerce to support your website, follow the instructions below:
Note: If you do not see an entry in the Ecommerce Site URL field, contact your ECI Support Specialist, so they can get it setup for you. If you have sufficient permissions, you may be able to add your URL to the field manually. Your EvolutionX API Key must be active as well.
The Ecommerce top menu option does not display if this entry is missing and the Active API Key check box is disabled.

  • Verify Delivery Postal Code Select this option if taxes for the delivery rates for online orders vary based on the customer's local postal code (specific to U.S. deliveries). When you select this option, the application searches for the delivery postal code and applies the tax rate for the delivery charge associated with that location. In some non-U.S. regions, delivery tax rates are uniform across postal codes, so this option is not required.
    Note:  You set the postal code options in the Zip Codes / Post Code Maintenance form (Maintenance > Database > Zip / Post Codes). See Zip/Postal Codes for these instructions.

  • Require Cart Verification
    Select this check box to require the application to verify the delivery, discounts, adjustments, and totals in the online order.
    This check box selection is required for Spruce eCommerce websites.

8. When you have completed these settings, choose Process (F12) to save them to the database.

Setting up the Ecommerce Adjustment Codes

There are several adjustment codes that the application uses to process incoming orders and quotes from the API. This section explains how these codes should be set up to ensure that they work properly and the positive and negative adjustments show up in the General Ledger accounts as expected.

Setting up the Delivery Charge Adder Code

The Delivery Adder is typically supplied to the application when the online order requires delivery. The amount supplied by the API is applied to the imported transaction using this adder code. Not all API orders have a delivery charge (as in the case of Buy Online, Pick Up in Store (BOPIS)), but when the delivery charge applies, the application uses this adder to apply it.

To set up the Delivery charge adder:

1. From the Main Menu, go to Point of Sale > Database > Adjustment Codes. The Adjustment Codes Maintenance form displays.

2. Complete the fields in this form as follows:

  • Adjustment Code / Description
    Type the name of the Delivery Code adder in the Adjustment Code field and a description of its purpose in the Description field.
    Typically, the entries are something like ECOMDEL (no spaces) and Delivery Adjustment for Ecom Orders.

  • Category
    Choose Point of Sale in this field.

  • Adjustment Type
    Choose Adder in this field.

  • Method
    Choose Manual Entry in this field.

  • Pro-Rate By
    Choose Invoice in this field. (Recommended)
    Note: You may want to select a different Pro-Rate By option for this setting. See Point of Sale > Adjustments > Pro-Rate By to learn more about this option.

  • Default Amount
    If there is a default charge for delivery, enter it in this field.
    If not, leave this field blank.

  • Cost Percentage
    If the charge is a percentage of the order, enter the percentage in this field.
    If not, leave this field blank.

  • Discountable
    If you want to apply a discount to the delivery charge, select this check box.
    If not, leave this box unchecked.

  • Taxable Adjustment
    If the adjustment is taxable, click this check box.
    If not, leave this check box unchecked.

  • Income/Cost/Payables
    Choose the appropriate GL account for each of these options.

3. When you have completed these selections, click Process (F12) to save the adder.

This entry will display when the user selects the Adder Code option in the Ecommerce tab.

Setting up the Delivery Discount Adjustment Code

The Delivery Discount Adder allows you to refund the delivery charge amount if your business decides not to charge for delivery, but there is a delivery charge in the ecommerce order.

To set up the delivery discount adjustment code:

1. From the Main Menu, go to Point of Sale > Database > Adjustment Codes. The Adjustment Codes Maintenance form displays.

2. Complete the fields in this form as follows:

  • Adjustment Code / Description
    Type the name of the new Delivery Discount Code in the Adjustment Code field and a description of its purpose in the Description field.

  • Category
    Choose Point of Sale in this field.

  • Adjustment Type
    Choose Discount in this field.

  • Method
    Choose Manual Entry in this field.

  • Pro-Rate By
    Choose Invoice in this field. (Recommended)
    Note: You may want to select a different Pro-Rate By option for this setting. See Point of Sale > Adjustments > Pro-Rate By to learn more about this option.

  • Default Amount
    If there is a default discount amount, enter it in this field.
    If not, leave this field blank.

  • Cost Percentage
    If the discount is a percentage of the delivery charge, enter the percentage in this field.
    If there is no discount percentage, leave this field blank.

  • Discountable
    Leave this box unchecked. This is required.

  • Taxable Adjustment
    If the adjustment is taxable, click this check box.
    If not, leave this check box unchecked.

  • Income/Cost/Payables
    Choose the appropriate GL account for each of these options.

3. When you have completed these selections, click Process (F12) to save the new discount.

This entry will display when the user selects the Discount Code option in the Ecommerce tab, so be careful that you choose this for the Delivery Discount list instead.

Setting up the Discount Adjustment Code

The Discount Adder allows you to apply any discounts included in the online order to the imported ecommerce transaction.

To set up the discount adjustment code:

1. From the Main Menu, go to Point of Sale > Database > Adjustment Codes. The Adjustment Codes Maintenance form displays.

2. Complete the fields in this form as follows:

  • Adjustment Code / Description
    Type the name of the new Discount Code in the Adjustment Code field and a description of its purpose in the Description field.
    Note: Make sure the adder name clearly distinguishes it from the other ecommerce adjustments.

  • Category
    Choose Point of Sale in this field.

  • Adjustment Type
    Choose Discount in this field.

  • Method
    Choose Percent of Subtotal in this field.

  • Pro-Rate By
    Choose Invoice in this field. (Recommended)
    Note: You may want to select a different Pro-Rate By option for this setting. See Point of Sale > Adjustments > Pro-Rate By to learn more about this option.

  • Default Amount
    The entry in this field should be 0.00.

  • Cost Percentage
    Leave this field entry as 0.

  • Discountable
    Leave this box unchecked. This is required.

  • Taxable Adjustment
    If the adjustment is taxable, click this check box. If not, leave this check box unchecked.

  • Income/Cost/Payables
    Choose the appropriate GL account for this type of adder.

3. When you have completed these selections, click Process (F12) to save the new discount.

This adder entry will display when you select the Discount Code option in the Ecommerce tab.

Setting up the Default Tax Code

If the incoming order or quote comes in with a tax amount attached, the application uses the supplied tax code to calculate the taxes. If not, the application uses the tax code created here to calculate the applicable taxes for the transaction.

To create a default tax code for the ecommerce transactions:

1. From the Main Menu, go to Point of Sale > Database > Sales Tax. The Sales Tax Maintenance form displays.

Sales Tax Maintenance Form with Default Tax Entries

2. Complete the fields in this form as follows:
Note: Any fields not mentioned can be left as they are, except when you are setting a code specifically for clothing or food tax rates or tax zones apply.

  • Tax Code / Description
    Type the name of the tax code in the Tax Code field and a description of its purpose in the Description field. The Name on Invoice prefills with the entry in the Tax Code field.

  • Total Percent
    Leave the entry 0.0000 in this field.

  • Always Exempt
    This option cannot be selected/checked.

  • Use for Delivered Sale
    Select this check box if tax applies to deliveries.

  • Use Tax (% of Cost)
    Select this check box if it applies.

  • ECommerce
    Select this check box. This is required.

  • Level 1\Level 2\Level 3
    If different levels of tax apply (such as State, County, Municipal, etc.), complete these fields with the appropriate tax amounts. The system will use these fields to calculate taxes for incoming transactions. Select the Clothing Exempt check box for any level that applies.

  • GL Mapping: Cash Sales, Charge Sales, Cash Returns, Charge Returns
    Select the appropriate GL accounts to which each of these amounts should be applied.

  • Tax Table
    In some cases, sales tax is not calculated as an exact percentage based upon the transaction total. For example, some areas don't charge tax on amounts below a certain threshold and may also determine "break-points" specifying when tax is to be incremented. In these cases, a tax table is used to handle this situation.

3. When you have completed these selections, click Process (F12) to save the tax settings.

Setting up the Default SKU Requirements

The Default SKU is for non-stocked items and must be applied to all branches that participate in ecommerce.

To create a default SKU code for the ecommerce transactions:

1. From the Main Menu, go to Inventory > Database > Item. The Item Maintenance form displays.

Item Maintenance Form with Ecommerce Measures Entries

2. Complete the fields in the Item Maintenance Common > Measures tab as described below:

  • Item
    In this field, type the name of the default SKU for the ecommerce setup.

  • Group/Section
    Choose the group and section item type of the default SKU.

  • Item Type
    Choose Standard. This entry is required.

  • Measures
    Enter/choose the appropriate measure type for the default SKU. Typically, this entry is EA for Each.

  • Quantity Conversions
    Used when 1 means a pair, or a dozen, etc. Typically, these entries are 1 : 1 for the default SKU.

3. When you have completed the selections in the Measures tab, click the Codes tab.

Item Maintenance with Codes Tab Options Entered

  • Taxable
    Choose Yes or No, as appropriate for this SKU.

  • Discount Code
    Choose Discountable or Net, as appropriate for this SKU. This defaults to Discountable.

  • Qty Rounding
    Type N in this field.

  • Price Rounding
    Choose the appropriate option for this SKU. This defaults to No Rounding.

  • Description Reqd
    Type Y in this field. This entry is required.

  • Track Qty On Hand
    Type N in this field. Since this SKU is for a non-stocked item, this entry is N. This entry is required.

  • Tag ID Required
    Type N in this field. Since the Tag ID Required prompts requires that a serial number be entered for the item during sale, return, or rental, this entry is not needed.
    Note: None of the other options in this tab are required for this type of transaction.

4. When you have completed your entries in the Codes tab, click the Branch tab and the Codes tab.

Note: All branches that accept ecommerce business must have the setting discussed in this section.

Item Maintenance Form with Branch > Codes Options Entered

  • Stocked
    Type N in this field. This is required.

  • Returnable
    Type Y in this field. No other entries are required in this tab.

5. When these entries are complete, click the Pricing tab.

Note: All branches that accept ecommerce business must have the setting discussed in this section.

Item Maintenance Form > Branch > Pricing Options

IMPORTANT: No pricing or costs can be assigned to this SKU, but if discount amounts apply for a particular type of customer, complete the discount percentage amount entries before you move on.

6. When you have completed these selections, click Process (F12) to save the default SKU settings.

Setting up the Ecommerce Bank Card Type

This bank card setup must be unique to ecommerce and not be used for any other purpose. This bank card must not be integrated but must be enabled.
The application uses this code for all imported ecommerce transactions when the payment type is bank card (credit card).
Note: This setting must be completed by the ECI Implementation or Support team.

To create an ecommerce bank card:

1. From the Main Menu, choose Maintenance > Database > Parameters > Setup > BankCards. The Parameter Settings form displays.

Parameter Settings > Setup > BankCards Options

2. In the Payment Methods box, scroll to the bottom and add a new row.

3. In the Card Name column enter ECOM and select the Enabled but not the Integrated check box.

4. When you have completed these entries, click Process (F12).

5. Return to the Point of Sale tab and choose the Ecommerce tab.

6. From the Bankcard Type list, choose the ECOM option from the list.

7. Choose Process (F12) to save this setting.

Setting up the Totals Code

The application uses the Totals Code when the calculation that is in the ecommerce request does not match the local calculation, and it serves to balance the difference, based on the available information.

To set up a Totals Code:

1. From the Main Menu, go to Point of Sale > Database > Adjustment Codes. The Adjustment Codes Maintenance form displays.

2. Complete the fields in this form as follows:

  • Adjustment Code / Description
    Type the name of the Totals Code adder in the Adjustment Code field and a description of its purpose in the Description field.

  • Category
    Choose Point of Sale in this field.

  • Adjustment Type
    Choose Adder in this field.

  • Method
    Choose Manual Entry in this field.

  • Pro-Rate By
    Choose Invoice in this field.
    Note: You may want to select a different Pro-Rate By option for this setting. See Point of Sale > Adjustments > Pro-Rate By to learn more about this option.

  • Default Amount
    Enter 0 in this field.

  • Cost Percentage
    Enter 0 in this field.

3. When you have completed these selections, click Process (F12) to save the new adder.

This entry will display when the user selects the Totals Code option in the Ecommerce tab.

Understanding the Totals Code

When a Consumer places an order or requests a quote through an ecommerce website or ProLink and the transaction contains a different tax code from the default tax code, the final tax liability can be different from the submitted tax calculation. When this occurs, the application calculates the new tax amount for the transaction, which can result in a discrepancy between the imported total and internally calculated transaction total. For some transactions, the system can apply an adjustment during the import process, using the Totals Code setting. For others, the user needs to add a manual adjustment to ensure the transaction is processed successfully.

We have developed new processes and alerts to help users manage these transactions with tax differences and help them add the appropriate adjustments during the import process. Since existing adjustment codes can manage some of these issues, these prompts and changes help users navigate these tax liability issues they could face.

Note: These changes do not apply to imported quotes/orders from ProLink or orders from DoItBest BOPIS. The application handles these transactions as it did before this enhancement.

There are three conditions where this tax liability discrepancy can occur. This is how the application helps users resolve these tax-related issues.

When there is a difference between the imported transaction total and the total calculated after the application imports the transaction due to tax calculation differences, consider these scenarios:

Scenario 1: If the imported transaction has a valid tax code (that is not the ECOM parameter tax code) and the order/quote does not contain a deposit, the application adjusts the tax amount internally, applies it to the transaction using the Totals Code, and the transaction does not require a manual adjustment.

Scenario 2: If the imported order/quote has a valid tax code (that is not the ECOM parameter tax code) and the order/quote contains a deposit from the Consumer that does not pay the entire transaction balance, there is a manual process. When the user tries to accept the transaction, the application prompts them to remove the automatic adjustment. After the user clicks Yes, the following prompt displays:

Scenario 2 Alert Message

After the user clicks OK, they review the transaction, identify the appropriate tax amount, and create an adjustment to pay the proper tax. After they click Process (F12), a new message displays:

Scenario 2 Resolution Message

The user clicks OK and applies the custom adjustment to the transaction.

Note: The business pays the difference in taxes for this transaction.

Scenario 3: If the imported order/quote uses the ECOM parameter tax code and the transaction contains a deposit amount, but the calculated transaction does not reflect the deposit paid, the application prompts the user to reject the standard adjustment code. The user adds the deposit amount in the appropriate field to the data grid, and clicks Process (F12). This message displays:

Scenario 3 Resolution Message

After the user clicks OK, the application applies the custom adjustment to the transaction.

When processing an imported order/quote that contains a deposit, but not the entire transaction amount, warning messages display to warn the user that the totals and subtotals do not match the transaction amount:

Scenario 4 Warning Messages

  • If the user is processing a quote, the user can accept the warnings and continue.

  • If the user is processing an order, since the Consumer will be resolving the transaction balance when they pick up the order, the user can enter the cash amount required to complete the transaction, and click Finish (F12) to process the transaction.

Setting up a User/Group for Handling Online Orders and Quotes

After you identify and train users on your staff to manage incoming online orders and quotes, you can set up an alert that notifies these users when these transactions arrive. It makes sense to create a unique user group for this purpose to ensure the right people are informed immediately. You can create this group directly in the Ecommerce subtab.

To create a user group that for handling online transactions:

1. From the Main Menu, select Maintenance > Database > Parameters > Point of Sale > Ecommerce tab. The Ecommerce tab options display.

2. Beside the Notify User or Group list, click the Settings icon to create a list of users you want to notify when ecommerce activity occurs.
The User Group Maintenance list displays.

3. Use these fields to describe the group who will manage the incoming orders and quotes:

  • Group
    In the Group list, type the name for the new group, such as ECOM.

  • Description
    In the Description field, type a description of the new group, such as Ecommerce Notification team.

4. Scroll through the list of user IDs and select the check box beside the ID of each team member who can respond to the notification.

5. Click Apply to save your entries and selections.
The Ecommerce subtab redisplays with the new group notification team name.

6. After you complete the other settings you need for processing incoming online requests, click Process (F12) to apply this group to the application.

If you do not add this notification group, the application reminds you to do so with a warning when you try to close the Ecommerce tab:

  • User or Group has not been defined

If you create the group or add a username to this list and then remove the group or the user from the application, a warning message displays when you access this tab:

  • User or Group no longer exists

Ecommerce API Documentation

As with all help documentation, the Ecommerce help topic is proprietary and is for ECI customers only. If you would like a third-party web developer or other non-employee to receive a copy of the API documentation, ECI requires a current, executed NDA to access this documentation; please contact your After Market Account Manager to make this request.