How to Install ShipperHQ on Salesforce Commerce Cloud

Overview

ShipperHQ supports rating on Salesforce via our cartridge obtained through the Salesforce Marketplace. This article describes the steps for installation, how to test and other considerations. 

Prerequisites

Before performing the steps below, ensure you have:

  1. Created a ShipperHQ account at ShipperHQ.com
  2. Within the ShipperHQ dashboard under Websites create a new website and obtained an API Key and Authentication Code. Note the Scope under which your website is configured (noted in the top right corner of the dashboard). These credentials will be used to connect to ShipperHQ from the cartridge.
  3. Download the ShipperHQ cartridge ZIP file from GitHub.com. 

Steps to Import the Cartridge

  1. Within this ZIP you’ll find the int_shipperhq directory containing the cartridge & Install int_shipperhq_sfra cartridge code.
  2. Update your site’s package .json to include the cartridge by adding “&& sgmf-scripts –uploadCartridge int_shipperhq_sfra” to “uploadCartridge”
  3. In Business Manager > Administration > Sites > Manage Sites > Business Manager Site. Select the Settingstab and prepend “int_shipperhq_sfra:” to the beginning of the “Cartridges” path.
  4. In Business Manager > Administration > Sites > Manage Sites > {Select Site Name} . Select the Settings tab and prepend “int_shipperhq_sfra:” to the beginning of the “Cartridges” path.

Steps to Import Meta Data, Jobs, and Services

The ShipperHQ cartridge employs product meta data as well as a synchronization job to support the cartridge functionality.

These need to be imported as follows:

  1. Find the metadata directory under the ShipperHQ cartridge folder
  2. In the “jobs.xml” file, update the “site-id” attribute of the <context> tags as well of the values in theWorkingFolder and ArchiveFolder parameters to match your Site ID
  3. Compress the metadata directory under the ShipperHQ cartridge folder into a Zip file called metadata.zip
  4. In Business Manager > Administration > Site Development > Import & Export click the “Upload” button under “Import & Export Files” and select the Zip file from step three and click “Upload”
  5. Click the “Import” button and once the import shows as complete you can continue to the next step

Steps to Connect to ShipperHQ

The connection to ShipperHQ’s API is made using credentials and preferences set in the Site Preferences as follows.

  1. In Business Manager > Merchant Tools > Site Preferences > Custom Preferences select the “ShipperHQ” group
  2. Set “Enable” to “Yes,” set “Scope” to match the scope of your website in the ShipperHQ dashboard (see Prerequisites above)
  3. Enter the API Key retrieved from ShipperHQ in the “API Key” field and the Authentication Code retrieved from ShipperHQ in the “Password” field
  4. Save these settings

Steps to Synchronize Shipping Methods

Since the purpose of ShipperHQ is to provide shipping rates and options in real-time to a merchant’s clients’ shipping methods that will be made available from ShipperHQ must be pre-populated. This can be done automatically using the ShipperHQ Job as described below.

  1. Under Business Manager > Administration > Operations > Jobs select “ShipperHQ”
  2. Click “Run Now” to run the synchronization Job
  3. This Job will import shipping methods configured in ShipperHQ into Commerce Cloud
  4. Once the Job has completed, confirm shipping methods have been imported successfully under Business Manager > Merchant Tools > Ordering > Shipping Methods
  5. Shipping Methods can be reordered and their order will be respected with future runs of the synchronization Job
  6. This Job will need to be rerun whenever new methods are enabled in your ShipperHQ dashboard

Steps to Configure Product Attributes

Some of ShipperHQ’s functionality requires additional product attributes to be set on products. At a minimum, weight must be set (especially if you are using live rate carriers) but additionally attributes like length, width, height, ship-from origin, shipping group, etc. may be set. Most of these attributes accept plain numeric values (e.g. length, width, height, weight) but others must match values set in ShipperHQ in order to be recognized by ShipperHQ. Therefore, certain attributes as described below are of type Enum of Strings and must be set up prior to using them. We recommend setting these up as 1 word and if the name is more than 1 word use underscores to join, for example shipping_group, origin_1, dim_rule_1.

  1. Go to Business Manager > Administration > Site Development > System Object Types > Product > Attribute Definitions
  2. Find “shipperHQDimGroups,” “shipperHQShippingGroups,” or “shipperHQWarehouses”
  3. For each one ensure that you have entered the corresponding values from your ShipperHQ account. For example, if you have the following Shipping Groups configured in ShipperHQ: “Large,” “Medium,” and “Small” you would need to edit the “shipperHQShippingGroups” attribute and add additional values with those strings as the Value. The Display Value does not impact processing but it is recommended to keep this the same as the Value.
    1. “shipperHQDimGroups” corresponds to Dimensional Packing Rule Groups in ShipperHQ
    2. “shipperHQShippingGroups” corresponds to “Shipping Groups” in ShipperHQ
    3. “shipperHQWarehouses” corresponds to “Origins” in ShipperHQ
  4. Apply the attribute changes and move on to the next attribute. Repeat for all three of these attributes.

Steps to Configure Products

  1. Under Business Manager > Merchant Tools > Products and Catalogs > Products choose a product and edit
  2. In the ShipperHQ section, the following can be configured by product:
    1. “Origin Warehouse(s)” for merchants fulfilling from multiple locations, supports assignment of products to one or more warehouses pre-configured in ShipperHQ
    2. “HS Code” for merchants shipping internationally with real-time duties & tax calculations at checkout enter the 6 or 10 digit HS Code of the product
    3. “Ship Length” is the length dimension
    4. “Shipping Groups” for merchants using ShipperHQ’s Shipping Groups within their ShipperHQ dashboard configuration products can be assigned to one or more Shipping Groups
    5. “Ship Height” is the height dimension
    6. “Fixed Shipping Fee” for merchants who set a fixed shipping price for certain products
    7. “Ship Weight” is the weight of the product
    8. “Ship Width” is the width dimension
    9. “Dimensional Rule Group(s)” for merchants using ShipperHQ’s Dimensional Rule Groups to set specific packing rules for certain groups of products
  3. Only “Ship Weight” is required, all other fields are optional

Steps for Custom Code

No custom code is required.

External Interfaces

Shipping rate request web service calls are made to ShipperHQ’s web services at api.shipperhq.com. All traffic uses the HTTPS protocol.

Requests include:

  • Ship-to address
  • Shipping-related product attributes for all products in the cart

Responses include:

  • Available shipping services
  • Shipping rates for each service
  • Optionally may include delivery date

Firewall Requirements

ShipperHQ requires outbound requests to api.shipperhq.com via HTTPS therefore port 443 access is required for outbound traffic.

Testing

Connect to ShipperHQ and Synchronize Shipping Methods

  1. Within the ShipperHQ dashboard, under Websites edit your Website and copy the API Key shown then click the “Generate New Authentication Code” button and confirm then copy the Authentication Code shown
  2. In Business Manager > Merchant Tools > Site Preferences > Custom Preferences select the “ShipperHQ” group
  3. Set “Enable” to “Yes,” set “Scope” to match the scope of your website in the ShipperHQ dashboard (see Prerequisites above)
  4. Enter the API Key retrieved from ShipperHQ in the “API Key” field and the Authentication Code retrieved from ShipperHQ in the “Password” field
  5. Save these settings
  6. Under Business Manager > Administration > Operations > Jobs select “ShipperHQ”
  7. Click “Run Now” to run the synchronization Job
  8. This Job will import shipping methods configured in ShipperHQ into Commerce Cloud
  9. Once the Job has completed, confirm shipping methods have been imported successfully under Business Manager > Merchant Tools > Ordering > Shipping Methods
  10. The methods shown should match the methods configured in your ShipperHQ dashboard

Set Product Attributes and Test Rating

  1. Under Business Manager > Merchant Tools > Products and Catalogs > Products choose a product and edit
  2. Lock the product to allow editing
  3. Enter a value in the “Ship Weight” field
  4. Save and unlock the product
  5. On the frontend of the Commerce Cloud site, choose that product and add it to your cart
  6. Continue to checkout (checkout as guest or log in)
  7. Enter your Shipping Address and shipping rates will be retrieved from ShipperHQ

Operations, Maintenance

Data Storage

The cartridge itself does not store any data.

Availability

ShipperHQ maintains an uptime of over 99.96% annually on all web services. Though exceedingly uncommon, should any downtime or service impact be expected due to scheduled maintenance or system updates, clients are notified in advance of any such event. Additionally, support is available 24/7/365 via email & phone for clients who believe they are experiencing a service outage. We also employ multiple layers of internal and external monitoring ensuring action can be taken immediately in the case of any system issues.

Failover/Recovery Process

It is recommended that merchants have basic shipping methods configured within Commerce Cloud which remain disabled at all times except during a service outage. In the event of an outage, shipping rates will not be shown to customers by the ShipperHQ cartridge and the merchant should temporarily enable these native shipping methods and notify ShipperHQ. The native shipping methods should be disabled once service is restored.

Support

ShipperHQ support team is available by email at support@shipperhq.com or during business hours by phone at +1 (512) 215-4900 and +44 (0)1722 446240. Support business hours are 3:30 AM – 6:00 PM US Central time weekdays except for holidays. Support for critical issues is provided on weekends and holidays via email or voicemail. Outside of those hours, phone voicemail messages and emails are monitored 24/7/365 for urgent issues.

User Guide

Roles, Responsibilities

The store admin should follow the setup instructions included in this document to add the ShipperHQ cartridge and configuration.

There are three recurring tasks which merchants may undertake as required:

  1. Update product attributes such as Shipping Group, Origin, etc. as required as new products are added to the Commerce Cloud catalog.
  2. If the merchant configures new shipping services in ShipperHQ, run the ShipperHQ synchronization Job to add the new services to their Commerce Cloud shipping services. The running of this Job is described in detail in the Implementation Guide above.
  3. If a customer utilizes method merging they need to make sure to create the shipping method manually, as the job does not bring over method merge codes “shqmulticarrier_METHODCODE”

Storefront Functionality

No new storefront functionality is included with this cartridge.

Considerations 

If a customer proceeds to checkout and receives shipping rates but then leaves checkout and makes changes to the quantity or items in their cart, the previously calculated shipping rates will still be displayed in the cart.

Was this doc helpful?