What is Spruce ERP?

Spruce® ERP software is a end-to-end business management software solution specifically for home lumber and building materials 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
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

Learn how to setup live pricing and inventory (stock) from our dedicated article.

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

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.

Invoice Payments - Two types of Spruce Accounts

Balance Forward: These accounts will only be allowed to make bulk payments against the account.

Open Item: These accounts will be allowed to pay individual invoices through the store.

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.

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)

We support non-stock items using the below.

Template SKU - Product level
Vendor Codes - Supplier level

How the logic works for non-stock items

EvoX does a live price lookup
- If the product or supplier have either/both of the below, we will pass it to Spruce in the live pricing request.
  - 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.

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.

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.

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.

👍 Important: Add-on SKU are added regardless of the customers location.

Display UOM

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:

FAQs

Totals not matching in Orders error

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.