ECI Spruce ERP Integration

Spruce Sync App for EvolutionX with details about setup, use cases, how customer sync works and more.

Pedro Pinto avatar
Written by Pedro Pinto
Updated yesterday

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
    โ€‹

  • 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

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)

๐Ÿ‘ Important: Spruce version 26.6 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:
โ€‹


โ€‹

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.

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.

  1. Spruce version should be at least v26.6

  2. You have a Vendor Template Item setup in Spruce

  3. 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"


Did this answer your question?