What is Spruce ERP?
Spruce® ERP software is an end-to-end business management software solution specifically for lumber, building materials, and hardware suppliers.
👍 Important: Orders can only be created via the storefront. Admin order creation can be started but must be completed on the storefront by the customer. The cart verification, product verification (tally types, etc), and tax calculations between Spruce and EvolutionX work through the checkout process on the storefront.
Install from the App Store
Enable the ECI Spruce ERP App from the App Store under the ERP category. Go to the EvolutionX Admin and click App Store → ECI Spruce ERP Integration.
ECI API Endpoint URL: Set the API endpoint provided by ECI
ECI SOAP Endpoint URL: Set the SOAP endpoint provided by ECI
API Key: Set the API Key provided by ECI
Shipping Country Code: Sets the country code for all shipping user addresses when synchronising Spruce customers with EvolutionX. ISO Alpha-2 code must be used
Guest Customer Account: Sets the Account number that is going to be used for guest users
ERP Order Discount Product SKU : Sets the SKU that will be used for order level discount
👍 Important: Discounting isn't supported for stores with Non-taxable product.
Auto Process Account Balance/Invoice payment In Spruce: The toggle determines if account balance and invoice payments are to be auto processed in Spruce. The default setting is true
Auto Process Orders In Spruce: The toggle determines if orders placed on the storefront are to be auto processed in Spruce. Below are the options available:
Auto Process Orders: Select this option to always auto process all orders in Spruce
Do Not Auto Process Orders: Select this option to not auto process any order in Spruce
Only Auto Process Orders With No Order Notes: Select this option to only auto process orders in Spruce if the order does not have an order note
Map checkout order notes to Spruce delivery note field: The toggle determines if checkout order notes are mapped to Spruce delivery notes. If toggled on, the checkout order notes will have a character limit to avoid the notes being cut off in Spruce Order and Invoices PDFs.
Spruce order notes (Sent along with the Order id): Sets the value to show under the Order ID in Spruce Order and Invoice PDFs. Read More Here
Environmental Fees: Apply Environmental Fees to certain products as soon as they're added to the cart. Read More Here
Convenience Fees on Account/Invoice payments: The toggle determines if on account/invoice payments have convenience fees defined in Spruce for each payment method. Read More Here
Convenience Fees Message: Tooltip to show to the user explaining the convenience fee. This message will override the message defined in Spruce.
Error notification e-mail Sender: SES E-mail address to be used as sender (FROM) for emails sent when an integration error occurs.
Error notification e-mail Receiver: E-mail address to receive (TO) information when an integration error occurs.
Live Pricing & Inventory (Stock) Setup
Customer Account, Job(Child Account), and Address Sync
Each night a one-way sync of all accounts, Jobs(child accounts in EvoX), and Addresses is pulled from Spruce customers tables and will create or update customers on EvolutionX.
👍 Important: Any Account or Address in EvoX that has an Account code and Seller reference will be updated by the sync process. Any existing data will be overwritten with the Spruce data, as Spruce is the owner of those records.
You can also trigger a one-way sync of all accounts and child accounts from the ECI Spruce ERP App Store in EvolutionX.
Customer Field Mapping
Here are some important EvolutionX fields and how they are mapped with data from Spruce.
Customer Account Number — EvolutionX sets this value as the Spruce Customer Account Number.
Customer Seller Reference — EvolutionX sets this value as the Spruce Customer Job value.
Customer Account Name — EvolutionX sets this value as the Spruce Customer Name.
Customer Branch — EvolutionX sets this value as the Spruce Customer.
Customer Address — EvolutionX sets this value as the Spruce Customer Address.
Pricing Override AddToCart — All accounts with Spruce Status "On Hold" won't see the "Add to Cart" button in the Storefront.
Account Status — All parent and children account with Spruce Status "Active", "Inactive" and "On Hold" will be enabled on the EvoX, but the ones with "Disabled" or "Closed" status will be disabled.
Credit Status — All accounts with Spruce Account Type "Charge" will have the Credit Status enabled in EvoX. The child accounts inherit the credit status of the parent.
N.B - Accounts disabled through the sync process can only be enabled from the admin
Credit Status / On Account Payments
👍 Important: The child accounts inherit the credit status of the parent. Credit status changes in EvoX will be overridden every night when the sync runs.
Customers are able to pay "On Account" when their Account is set to Credit enabled.
Admin
Checkout
The Customer Account in EvoX will be updated every night with the credit account status from Spruce. This is what control the "On Account" payment button. If you have credit, you get the button. If you don't have credit, the button should be removed.
We are not evaluating orders in real time during checkout to determine if an account is over their allocated budget.
When Spruce receives the order
If the "Enforce Credit Limits" parameter is enabled for the API (In Spruce), orders can still be submitted, but whether the order is automatically processed or must be manually imported and reviewed is what the "Enforce Credit Limits" parameter determines.
The "Enforce Credit Limits" parameter works in conjunction with the Credit Limit Override setting on the customer's account. If the credit limit override is set to "No password required", then the submitted order will be auto processed regardless of if the order total exceeds the customers credit limit
The other credit limit override values will auto process or require manual processes based on some criteria
Store Mgr Password and Credit Mgr Password
If set and the order total exceeds the accounts credit limit, then the order will be queued and need manual import, review and processing
Credit Mgr Password if 30 + balance
If set and the order total exceeds the accounts credit limit, and the account is carrying a a past due 30 day balance, then the order will be queued and need manual import, review and processing
Credit Mgr Password if 60 + balance
If set and the order total exceeds the accounts credit limit, and the account is carrying a a past due 60 day balance, then the order will be queued and need manual import, review and processing
Credit Mgr Password if 90 + balance
If set and the order total exceeds the accounts credit limit, and the account is carrying a a past due 90 day balance, then the order will be queued and need manual import, review and processing
Credit Mgr Password if 120 + balance
If set and the order total exceeds the accounts credit limit, and the account is carrying a a past due 120day balance, then the order will be queued and need manual import, review and processing
Payments Methods
Credit Card Payments
This includes tokenizing credit cards on the storefront, authorizing the amount of the order, and passing the token to Spruce for capturing the payments.
Invoice
Supported Payment Gateways
BlueSnap
Opayo
Nuevi
Card on file (Spruce)
Spruce Card On File Credit Card Payments
On Spruce ERP installations that support credit card payments, including US and UK customers, some card on file payment features can be supported on EvolutionX.
Card on File for Payment of Storefront Orders — Available if the user role enables it and a card is already stored on Spruce for the customer's account.
The card on file is selected at checkout as the payment method and Spruce will charge the card at the normal time during the order processing steps in Spruce.
Card on File for Invoice Payments — Available if the user role enables it and a card is already stored on Spruce for the customer's account.
The card on file is selected after the invoices have been chosen for payment. The card is either charged immediately or when processed by staff based on the "Auto Process Account Balance/Invoice payment In Spruce" toggle in Spruce app.
Invoice Payments and Paying Balances Setup
The storefront customers have the ability to pay invoices if they have their roles allowing the viewing of Invoices. This can be done in the Roles.
If the storefront user has access to the Invoices or Account Balance screens, they will be allowed to pay using the card on file in Spruce.
View ERP Cards on File allows the customer to use the card on file in checkout.
👍 Important: This permission View ERP Cards on File can't be set for roles used by guest users.
Invoice Payments - Three Types of Spruce Posting Accounts
Using Spruce, Customers have many choices for paying their charge accounts. They can pay all their bills monthly in one payment, they can pay monthly by job, they can pay monthly by invoice and/or job, and they can pay by invoice with special discount terms for early payment. Each of these posting account types can be broken down by account or job:
Balance Forward: These accounts make bulk payments against the account or by job. Accounts that pay within a certain time, get a discount.
Open Item: These accounts make payments by invoice and collectively get a discount if they pay by a certain date. Invoices can be grouped by job.
Open Item (Terms): These accounts make payments by invoice only, and the amount of discount applied depends on the date the individual invoice is paid.
Paying Invoices & Balance Forward by credit card
You can enable customers to pay their balance forward accounts or Invoices by enabling it via the payment methods.
Supported card types
BlueSnap
Opayo
Nuevi
Card on file (Spruce)
Orders
Make sure to tick "Require Cart Verification" for orders to be successfully sent to Spruce.
Delivery Taxes
You can setup the taxes for delivery in the following screen in Spruce system.
Sales >> Database >> Adjustment codes
For delivery orders the zip code used for tax calculations is the zip code from shipping address defined by the user in checkout. Where a zip code doesn't exist against the Shipping Address, the country code will be used.
For collection orders, the zip code used is from the selected collection branch. Where a zip code doesn't exist against the Branch Address, the country code will be used.
👍 Important: No delivery taxes should be set in EvolutionX. All taxes must be configured in Spruce.
Spruce Order Notes
Enabling the "Map checkout order notes to Spruce delivery note field" toggle will set a character limit in EvoX checkout order notes, to prevent the notes being cut in Spruce PDFs (green box) and will show a field to insert the "Spruce order notes". This text inserted in this field will be presented in Spruce Order and Invoices PDFs (red box).
Non-Stock Item Support (Template SKU, Vendor Codes)
👍 Important: Spruce version 27.0 or later.
To setup your non-stock items (e.g. Orgill & Do it Best), you will need to add your Vendor Code and Template SKU. Set that at the supplier level.
If you need to override the Template SKU at the product level, add it here at the product level.
We support non-stock items using the below.
Template SKU - Supplier level or Product level
Vendor Codes - Supplier level
How the logic works for non-stock items
EvoX does a live price lookup
If the supplier has both of the below, we will pass them to Spruce in the live pricing request. If the product has the Template SKU, we'll send that to Spruce instead of the supplier's Template SKU
Template sku in EvoX
Vendor sku in EvoX
Product UOM Logic
If Vendor sku exists
pass Spruce UOM
If both Vendor sku and Template sku exists
pass Spruce UOM
If Template sku exists and "Include UOM" toggled on
pass EvoX UOM
If only Template sku exists
pass Spruce UOM
Spruce then will check for the following
If product is in inventory based on the sku (Regular own products)
return Price and UOM
If Template sku exists (Special Order items - e.g. Windows)
return Price and UOM
If Vendor sku (DIB products)
return Price and UOM
Convenience Fees
👍 Important:
Convenience fees are only applied to Invoice or AR Balance payments. Convenience fees on an order is not currently supported.
Fees are only added to Credit Card Payments or Card on File payments.
Spruce version 26.6 or later.
You can enable the "Convenience Fees" toggle in Spruce app and define a information message (this message will override the message defined in Spruce). With this toggle enabled, when a user makes an on account or invoice payment, a percentage of the total amount will be added to the total. This percentage is based on a configuration made in Spruce for each payment method. To see how this is set up in Spruce, see this article. If this is enabled and a payment method used in EvolutionX is not configured in Spruce, we will use the default percentage fee defined in Spruce.
Default Bankcard Type that is set in the branch will be used, if a match isn't found
Payment Methods setup
Spruce app toggle
Storefront payment method card
Invoice payment email
Add-on SKU
👍 Important:
This feature is only available for Spruce customers with Spruce version 26.6 or later.
Add-on SKU are added regardless of the customers location.
In Spruce, you have the capability to incorporate additional products alongside existing ones. In EvolutionX, we use this feature to apply Environmental Fees to certain products as soon as they're added to the cart. To enable this functionality, simply designate an Add-on SKU within Spruce for the desired product.
After that, you need to enable the "Environmental Fees" on the EvoX Spruce app.
Then users will encounter a message associated with the product during their searches or when reviewing items in their cart.
At checkout, once the user has selected their preferred delivery options, the additional product will join the cart, updating the total price accordingly.
The order details will also include information about the additional product.
Display UOM
👍 Important: Spruce version 26.6 or later
If your store has Spruce live pricing it is possible to show another Unit of Measure per product in store front (including configurable products). To show the UOM display on the storefront, simply add in the UOM that exists in Spruce. During the loading of the page we will call out to spruce and get the associated price based on this UOM. This UOM is for display purposes only and not used for pricing of products.
👍 Important: This feature requires the "Include UOM" toggled on. See here how to enable it.
This is how it is displayed in store front:
Zero Priced Items
You can now place orders that include zero-priced items or consist entirely of zero-priced items using Spruce ERP. By turning on the zero-priced items toggle, these items are accepted and processed by the system.
Invoice Statement Discounting Terms
👍 Important:
Please note that this feature requires Spruce version 28 or later. Please contact our Spruce team to learn how to configure on Spruce.
To enable Invoice Statement Discounting Terms in EvoX Spruce, navigate to the EvoX Spruce app settings. Locate the toggle labeled "Invoice Discounting Terms" and turn it on to activate this feature.
Once the Invoice Discounting Terms feature is enabled, the Storefront Account Overview screen will display a new select dropdown based on the account type. The options in the select will vary as follows:
For Balance Forward Accounts, the select will include the options "Outstanding Amount", "Last Statement," and "Custom Amount."
For Open Item Accounts, the select will include the options "Outstanding Amount" and "Select Invoices."
If there is any discount applicable to either the on-account payment or the invoice payment, the system will display the discount amount and, if applicable, the discount date.
Account Overview
Invoices Grid
Payment Screen
Consolidated Payments
👍 Important:
Please note that this feature requires Spruce version 29 or later.
To enable Consolidated Payments in EvoX Spruce, go to the EvoX Spruce app settings. Find the toggle labeled "Consolidated Payments" and switch it on to activate the feature.
Once enabled, users can pay invoices from multiple jobs in a single transaction, including any applicable Finance Charges.
Invoices Grid
Payment Screen
FAQs
Totals not matching in Orders error
Check Delivery Tax isn't setup
If you don't have your tax setup correct in Spruce and Matching EvoX. Check this section to more details.
Check Cart Verification is Enabled in Spruce
The "Require Cart Verification" parameter and the "Allow zero price on items" should be set on the system. Check this section to more details.
Orders without delivery taxes
All taxes are calculated in Spruce. To have delivery taxes in Orders, they need to be defined in Spruce. Check this section to more details.
Is the Global Payments gateway supported for credit cards?
No, we do not currently support the Global Payments (Cayan) gateway.
Enforce PO
If a PO number is required during checkout, but the role does not mandate it, please verify whether the Global Account (for guest users) or the specific account has not enabled the 'CustomerPORequired' option in the Spruce system.
How to setup different pricing scenarios in Spruce
Spruce is a complex ERP that allows you to setup products in multiple ways to suit your internal staff. Positioning your products on an ecommerce store is a new scenario and you may need to display products and pricing in a particular way. Review a few workflows to suit your needs.
See pricing workflows
See pricing workflows
What Tally types are supported
Learn more about what tally types are supported and how to set them up in EvoX
Running Do it Best and Orgill Catalogs
In order to run your DIB or Orgill catalogs you will need to following.
Spruce version should be at least v26.6
You have a Vendor Template Item setup in Spruce
You have a Template Item for Pricing setup in Spruce.
The delivery date always gets set to the following day in Spruce
The Deliver On date will be set based on the system parameter setting in Spruce for the "To Be Delivered Days" which is set to 1 Day (next day). This is intended to be a place holder delivery date for the Order can can/should be arbitrarily changed by the Merchant based on factors that can/will dictate when the order can actually be delivered i.e. Truck availability, route planning, special delivery requests etc.
There is not a way to set in Spruce system the preferred delivery date based on the passed in Delivery Notes from EvoX. We only allow an order to be requested as delivery, and the final delivery date is then up to the Merchant as stated above.
The Merchant should be reviewing the Orders in case special notes are passed either involving delivery or some other request by the customer. This can be done either in the Orders transaction, or by the Dispatcher in the Deliver module in Spruce.
It's also possible place the orders with the AutoProcess flag set to False from EvoX, which then would require the Merchant to manually import, review, and process each online order giving them a chance to immediately review any special notes. See "Auto Process Orders in Spruce"
Store logo is not showing in Order and/or Invoice PDF
If the store logo is not showing in the Order or Invoice PDF on the Storefront, please contact the Spruce support team. Only they can insert the logo into the Spruce system, as this action requires their direct intervention.
What is the difference between the Date and Days fields in the Invoices grid?
In the Invoices grid, there are two fields: Date and Days.
The Date field shows the Invoice Issue Date.
The Days field displays the number of days remaining between today and the Invoice Due Date.
Can I pay invoices from multiple jobs at the same time?
If you're using Spruce version 29 or later , you can pay invoices from multiple jobs simultaneously by enabling the Consolidated Payments feature (see here).
Otherwise, this functionality is not supported. If you have already selected invoices from one job and attempt to select invoices from another, you will receive the following warning message:
To proceed, you must either complete payment for the current selection or discard it to start a new selection from the other job.