Web Store

Acctivate's web store integration allows you to connect to a web store and import customer and orders as well as export inventory availability and shipment tracking.

This section also covers the Configuration Manager's Web Store Options.

Overview

The Acctivate Web Store Integration can synchronize new customers, orders, item availability and tracking numbers in a single click from one or multiple web sites. The web store integration does not export product or customers from Acctivate to the webstore.

For example, if you create a product or customer in Acctivate, it will not automatically export from Acctivate and create that record on the webstore. This information will need to be manually created or imported into the webstore.

Acctivate uses the term “Web Store” to refer to the commerce portion of your web site. A Web Store typically consists of the following:

  • Customer List
  • Item List with Pricing
  • Quantity Available for Items
  • Shopping Cart
  • Sales Orders
  • Payment Processing
  • Shipment Tracking
Note

Acctivate does not provide a “Web Services API”. Instead, we leverage the existing API provided by your Shopping Cart / eCommerce platform. “Web Store API” is used below to represent the API provided by the eCommerce platform, not Acctivate.

Template

Acctivate uses a “Template” for each of the supported Web Store. Each template includes the following:

  • Web Store template Type (e.g., Shopify)
  • Web service API URL
  • Login and/or password
  • Field mapping
  • Field conversions
  • Default field values
  • Last sales order number or sales order date imported
  • Other configuration options (e.g., Create customers from orders)
Tip

Acctivate can be integrated with any shopping carts that has a template within Acctivate. However, we have also published our own, native XML schema that can be implemented by your web developer. This creates integration options for custom and less-popular shopping cart software. For more information, view our documentation on using the Native Acctivate Web Store Template.

Customers

Acctivate can be configured to automatically create new customer records from the web store. There is an option per template to import in new customers that have been created on the web store. These may be customers who have created an account, but have not checked out yet. By importing in the customer's web store profile, more information is typically available for Acctivate to use when creating a customer.

Another option available per template is to create customers for guests. Guests are customers who have created a sales order but have not created a customer profile on the web store. If this option is enabled Acctivate will import in this sales order with the customer information provided, such as the Bill To and Ship To address. A customer will be created in Acctivate based on the customer information provided with the sales order.

When importing customers or importing sales orders, Acctivate will attempt to match the web store customer to an existing customer in Acctivate first. If a match cannot be made, a new customer will be made unless the options to import customers and create customers from guests is disabled. If both of those template options are disabled, Acctivate will import in the sales order without a customer linked. Another option is to set a default customer for all import Sales Orders. For example, all web store orders imported from a Shopify web store could be imported in with the customer "Shopify Customer".

Alternatively, there is also an option to create individual customer records in Acctivate but sync all their customer transactions (invoices and payments) to QuickBooks under a single customer. The mapping page of the web store template allows you to set a default Synchronize as {Customer} value which will be used for all new customers created.

Sales Orders

Acctivate downloads new sales orders directly from the Web Store API. New orders are imported sequentially by either the order ID/number or created timestamp.

A mapping utility is provided to handle most special circumstances. For example, you may want to import a custom field on your web site to the Acctivate Sales Order Reference field. Default mappings are provided.

A mapping and conversion utility is included to handle most special circumstances and data discrepancies. For example, the “checkmo” payment method in your web store may be mapped to the “Check” payment method in Acctivate/QuickBooks. Another example would be mapping a custom field to the Acctivate Sales Order Reference field.

There is also a mechanism to define “Default Values” for constant values for all imported sales orders. For example, you could set the Marketing Code, Salesperson and/or Branch for all sales orders from the web store.

Acctivate includes a function to re-import any specific orders that previously failed. For example, an order may be skipped if an unrecognized field value is discovered (e.g., unknown product). Skipped sales orders will appear on the Web Orders tab of the Business Alerts window.

Tip

Acctivate can process credit card information imported in with a sales order; or, a credit card authorization can be imported in and captured at the time of invoicing. Typically, credit cards are processed by the web store at the time of checkout and the payment information is imported with the order.

Item Availability

If supported, Acctivate can use the Web Store API to update the web store's item availability to match Acctivate.

You can choose which products should be included in the export (by enabling the product's Available on web option) as well as which warehouses are included.

Refer to the Integrations section of this site for more information on options and configuration specific to your web store.

Shipments

Acctivate can use the Web Store API to mark sales orders as “Shipped”.

Note

This functionality may not be available for all Web Stores.

This option can be enabled or disabled per template. Refer to the Integrations section of this site for more information on options specific to your web store.

The shipment export includes the carrier and tracking number(s). Acctivate keeps track of the original Web Store Order ID, which may or may not be the Acctivate order number, and uses that to match the Acctivate Shipment to the web store order.

The Package Shipment module supports packing a kit's components into different packages for shipment. During the web store shipment export Acctivate will start with the first package and continue summing kit components across all packages available for export. The last package containing the components needed to fulfill the kit quantity will have its tracking number exported and associated with the kit product in the web store.

Creating a Template

As mentioned above, Acctivate has pre-configured web store templates which are used to communicate with the web store's API.

Below is an overview of the different web store template screens. While the setup is generally the same, each template may have different setup steps and configuration options. Refer to the appropriate Integration guide found in this documentation's table of contents.

Add Template

To begin, you must setup a new web store template:

  1. Go to File → Import Sales Orders and click Create to create a new template.
  2. In the Add Template screen, enter the following information:
    • ID: Enter the web store ID. This name must be unique. It is limited to 15 characters. This name can be displayed in the Order Manager as the Origin ID.
    • Name: This is the user friendly name that will appear in the Web Store Sync window. This can be up to 50 characters and may contain spaces.
    • Notes: Optionally, enter any Notes. Notes entered here are only visible when editing this web store template.
    • Type: Select the Type of Web Store.
  3. Click Next.

Source

The source screen allows you to select which pre-configured template will be used.

Refer to the Integrations menu in this documentation's table of contents to view the setup instructions for a specific web store template.

Template Options

Click the Next button on the Source page to get to the Options page of the template window.

The options screen shows import and export options available for the selected template.

Refer to the Integrations menu in this documentation's table of contents to view the options available for a specific web store template.

Source Values

Warning

The Source Values screen of the web store template is for advanced users only. Use caution when modifying XPath expressions.

Setting the Show advanced configuration settings template option to Yes will enable the viewing and modifying of the Source Values screen. If that option is set to No, this screen is not displayed.

When a web store synchronization is started, Acctivate requests orders and/or customer information from the web server. The response from the web store is a preformatted and includes order and customer information identified by specific elements or objects.

The Source Values page uses the query language XPath (specifically XPath 1.0) to navigate and return values based on the preformatted response. Each web store template has default XPath expressions which return a value from the web store's preformatted response. Each XPath expression is assigned a Name which can be used to simplify the mapping process.

When viewing the Source Values screen, you will find four sections: Subdocument, Namespaces, Tables, and Values.

Subdocument
The Subdocument can be set to customer or order based on which type of web store response you wish to view or modify XPath expression for. If you have the option to Import customers enabled, the web store will return a customer response file (unless the customer checked out as a "guest") which is used to create a Customer in Acctivate. When the "customer" subdocument is selected, the XPath expressions displayed below are apply to the web store's customer response file. Likewise, changing the subdocument to "order" will display the XPath expressions that will be applied to the web stores' order response.

Namespaces
Namespaces are used to avoid element name conflicts and remove ambiguity. For example, a web store XML response may include an <id> element for the order identifier and an <id> element for the customer identifier. By using a name prefix, such as o for the order and c for the customer (the prefixes used are arbitrary), this conflict can be avoided.

Not all web store responses include a prefix, however if the web store does use a Namespace prefix then it will exist here. Acctivate includes several custom XPath expressions that can be used to simplify more routine computations. These custom XPath expressions use the a prefix, so every web store template will have at least one Namespace defined.

The URI (Uniform Resource Identifier) is a string of characters which identifies an Internet Resource. The URI is not used as part of the mapping, its only purpose is to give the namespace a unique name. However, the URI may contain a pointer to a resource.

Tip

The Acctivate namespace URI (http://www.acctivate.com/xmlschema/) points to our Native Template documentation.

Tables
A subdocument (order or customer) can have multiple tables to map to. For example, on the Mapping screen, the subdocument Order will have a section for order header, order details and payment information. By default, each Acctivate web store template will have the appropriate tables enabled, but additional tables can be enabled by entering a value in the "Select" field, such as a . or a select statement.

For example, assume we have the following Native Template XML response (an excerpt):

<Result>
  <Order>
    <WebOrderNumber>123456</WebOrderNumber>
    <OrderDate>2021-01-01</OrderDate>
    <Type>O</Type>
    <!-- ... -->
    <OrderLines>
      <OrderLine>
        <VendorProductID>B10</VendorProductID>
        <Description>D-Ring Binder, 1" Ring, Black</Description>
      </OrderLine>
      <OrderLine>
        <VendorProductID>B15</VendorProductID>
        <Description>D-Ring Binder, 1 1/2" Ring, Blue</Description>
      </OrderLine>
    <!-- ... -->
  </OrderLines>
  </Order>
</Result>

Now, consider the following Native Template table entry:

Table Parent Table Select
Order /a:Result/a:Order
Detail Order a:OrderLines/a:OrderLine

Each order in Acctivate can have one value per field at the order header level, for example an order can only have one Order Date. The Order Table (used for the Order Header mapping) uses the /a:Result/a:Order Select statement to return the first elements between the XML elements. Since each order could have multiple order details, as our example above does, we need to define the detail section as being child section to the Order. To put it another way, we must define the Order table as the Parent Table to the Detail table/section. We can use the Select statement of a:OrderLines/a:OrderLine to return one set of detail fields per order line, however there can be any number of details per order. For example, the import will process the elements between as line one of the sales order, then process the second set of elements between , all while keeping it relative to the Parent Order.

Values
The Values portion of this screen includes all the XPaths. There are three components to the Values:

  • Name: The unique, arbitrary name assigned to an XPath. The Name is used on the Mapping screen.
  • Match: The expression used to select the starting node or node-set.
  • Select: The expression used to select and return the element or some computed value.

Consider the following Source Value entry from our Native Template:

Name Match Select
Line_VendorProductID /a:Result/a:Order/a:OrderLines/a:OrderLine a:VendorProductID

Using the Native Template XML response under the Tables section above, you can see that the Match statement will navigate down to the node as the starting point. The Select statement is used to select the element and return that value as the named field "Line_VendorProductID" which can be mapped to an Acctivate field.

There are numerous XPath expressions that can be used to evaluate different conditions. The expressions available are too great to list here, however the XPath expressions link at the top of the Sources screen directs to the official XPath 1.0 documentation. Additionally, the XSLT Patterns link directs to the XSLT patterns documentation. When comparing the two, XSLT patterns are used to identify nodes that an XPath select statement applies to. An XPath statement is used to navigate and return a field or a computed value. Acctivate includes custom XPath functions which can be viewed in the XPath Scratchpad window (see below).

Source Value page buttons
The upper right hand corner of the Source Values page contains four buttons: Query, Reset, Preview, and Scratchpad.

  • Query button
    To download a web store response file for a customer and/or order without trying to import it into Acctivate, use the Query button:

    1. Click the Query button at the top of the Sources screen.
    2. When prompted, click Yes to save the template.
    3. Enter the Web Store Order Number to import in that order. Leave blank if you don't wish to query that order. Click OK
    4. Enter the Web Store Customer ID to import in that customer. Leave blank if you don't wish to query that customer. Click OK The web store response files can be found in the Web Store log folder.

  • Reset button
    The Reset button will return the template's Source information back to its default configuration. This CANNOT be reversed so use caution.

  • Preview button
    The Preview button opens a Preview window in which you can load the web store's response file and preview the output based on the current Source values.

    You can open a previously downloaded source file by using the ellipsis button (...) or you can use the Query button in the Preview window which allows you to query a customer or order (see Query information above). At the bottom of the Preview pane and Output pane is a search box to quickly search for text.

    Alternatively, you can enter the XPath expression in the search box and check the XPath checkbox to search for that XPath location. Using our Native Template example previously referenced, if you search VendorProductID in the Preview pane and you don't have the XPath checkbox checked, you would see the VendorProductID node highlight as a match.

    However, with that checkbox still unchecked, if you searched Order/OrderLines/OrderLine/VendorProductID you would not see a match since that full string of text doesn't exist in the response. If you were to check the XPath checkbox, it recognizes my XPath expression as my search string and it would highlight VendorProductID.

  • Scratchpad button
    Clicking the Scratchpad button at the top of the Source screen will open the XPath Scratchpad window. The XPath Scratchpad allows you to test potential XPatch changes against an XML response file. To use the Scratchpad, do the following:

    1. Click the Scratchpad button at the top of the Sources window.
    2. On the Values tab of the XPath Scratchpad window that appears, click Load to lookup and select the XML response file you wish to translate. The path to the XML responses can be found in the log directory (e.g. \\{server}\AcctivateData\Log\WebStore\..\..\..\Protocol\).
    3. Enter in a Match statement.
    4. Enter in a Select statement.
    5. View the returned Results.

    Once your XPath statement is returning the expected values, you can add it to the Values grid in the Source screen with a unique Name.

    You can use the Tables tab of the XPatch Scratchpad to evaluate a table's Select statement. The Custom Functions tab displays a list of custom functions that can be used in Select statements.

    Note

    If your XML response file contains namespace prefixes, you must first remove the namespace from the XML in the Scratchpad preview and also remove the prefix from the nodes and your Match and Select statements in order for the statements to be evaluated properly. When setting up an XPath in the sources screen, add back in the appropriate prefixes.

Once you've made any modifications to the Source values, click Next to go to the Mapping screen.

Mapping

Each web store template has a default mapping. These mappings can be modified to meet your needs. There are four parts to the mapping:

  • Acctivate Field: The Mapping screen will list all the Acctivate fields that you can map to. They will be categorized under two primary headings:

    • Customer Document: This is the mapping used when creating a new customer from imported customers (the option to import customers must be enabled for the web store template). Mapping for the Customer document comes from the customer subdocument in the previous Source screen. Not all web store templates may have this option due to the limited customer information some web stores make available.
    • Order Document: This is the mapping used when importing orders. The mapping for the Order document comes from the orders subdocument in the previous Source screen.

    Both the Customer Document and Order Document have sub sections which can be expanded to see the Acctivate fields that you can map to. For example, order header information is found under Order Document→ Order and order detail information is found under Order Document→ Detail

  • Web store field: When you expand a section, you will see the Acctivate fields and the name of the web store field that is mapped to it. The web store field name comes from the Name field of the previous Sources screen. You can change the web store field that is mapped to an existing field, un-map a field or map a field.

  • Default Value: In some scenarios, you may not want, or be able to, map a web store field to an Acctivate field. Instead, you may wish to have some constant value populate an Acctivate field every time. For example, you may want all web orders that are imported in to have a Terms code of "Prepaid". It's unlikely that the web store provides a terms code value since all orders a paid at checkout, so instead you can use the Default Value field. Depending on the type of field, the Default Value may require you type in text or it may provide you with a list of options. In the terms code example given, you would click into the Default Value field next to the Terms Code field and select "Prepaid". It is recommended you un-map the Web store field if something is mapped there.

  • Conversions: It's not uncommon for the data values on your web store to mean the same thing as the values in Acctivate but have a different nomenclature. For example, your web store may have a Ship Via option of Second Day, but in Acctivate that Ship Via may be setup as 2nd day. Or, you may have the payment method American Express on your web store, but in Acctivate it's simply Amex. The Conversions field allows you to convert a web store field's value to a value that Acctivate recognizes. To use conversions, do the following:

    1. Click on the Acctivate Field on the Mapping screen to select it.
    2. At the bottom of the mapping screen, click Show Conversions.
    3. In the table that appears, enter the web store's value in the From field and enter the value that you want it to be converted to (the Acctivate value) in the To field. Repeat for each conversion.

The bottom of the Mappings screen contains a Summary... button. When you click this you will be prompted to save the template and then a text document will open up that summarizes all the changes to the default template configuration. Our support team may request this to help identify changes that were made and their impact.

Once you've made changes to the mapping, you can close the template which will prompt you to save, or you can click Next to get to the Import screen.

Import

On the Import screen, click Import Orders (or it may read as Validate Orders depending on the Import Options) to begin a Web Store Sync.

Web Store Logs

If the "Verbose Logging" is enabled (found on the Template Options screen of the web store template), Acctivate will download the customer and/or order request and responses. These files can be located in the Web Store log folder. If verbose logging is not enabled, only the sync messages log file is generated. The sync message log file contains the messages displayed in the Web Store Sync window.

  • Open the web store sync log folder from the Help menu.
  • In the WebStore directory, you will see a folder for each date that web store information was downloaded. The name of the folder will be formatted as yyyy-mm-dd.
  • If you navigate into that folder, you will see a folder for each time stamp that order information was imported in. The name of these folders will be formatted in 24 hour time as hh-mm-ss.
  • If you drill down into one of those folders, you will see a folder for each web store template that downloaded information during this time. You will also see a Messages.txt file containing the sync log.
  • Some web store template's download function is different than others. If you drill down into one of the web store folders, you may see a Protocol folder. The Protocol folder contains Acctivate's requests to the API and the responses from the API.

With each web store sync, Acctivate will delete one days worth of web store logs (a single sub-directory of the WebStore log directory). Only web store log folders with the format of yyyy-mm-dd that are older than 14 days will be deleted. This keeps the number of log files growing too large while still maintaining the two most weeks of logs.

Import Options

The Web Store Options in the Configuration Manager (File → Configuration Management → Web Store) apply to the Web Store import and the Sales Order import.

Provide confirmation before importing sales orders
When enabled, the Web/Sales Order import will perform a data validation step, but the orders will not be imported in until you confirm you want to continue with the import. The Web Store sync window or Sales Order Import window will display a Complete Sync button which, when clicked, will complete the import process.

Warnings
During a Web Store or Sales Order import a warning may be returned after the data validation step. If warnings are encountered, the import process will stop after the validation step so that you can review them and choose to proceed or not. If you choose to proceed, the warnings will be imported or skipped depending on the options below.

  • Import all orders
    If this option is selected and you proceed with an import that has warnings, the orders will be imported despite their warnings. For example, you've received a warnings that a product on the order is not found in Acctivate, the order will still be imported in and the product from the web store will be added to the Acctivate order as an "N" (non-standard) line type.
  • Skip orders with warnings
    If this option is selected and you proceed with a Web Store import that has warnings, the Web Store orders with warnings will be "skipped" which means they are not imported in, but rather they are placed in the Web Store tab of the Business Alerts. In the Business Alerts you can review the warnings and make any necessary corrections. The Web Store template has an option to automatically retry importing these orders with the next sync. Or, you can choose to resync from the Business Alerts tab. If this option is selected and you are using the Sales Order import, any orders with warnings are skipped, but they are not placed in the Web Store tab.
Tip

If using the web store import, it's recommended that you use the Skip orders with warnings option. This will allow you to import in valid orders and let you review any orders with warnings and retry them. With the Web Store sync, there are some instances where a warning is expected.

For example, a web order that has a payment being processed is not ready to import in yet. By skipping it, we can import in valid orders and then retry the skipped order at a later date, at which time the payment has been processed.