Skip to content
Visit ShipperHQ.com
  • There are no suggestions because the search field is empty.

How to Install ShipperHQ on Salesforce Commerce Cloud

Enable seamless integration of real-time shipping rates on Salesforce Commerce Cloud

Table of Contents

Overview

ShipperHQ supports rate calculation on Salesforce via our cartridge, available through the Salesforce Marketplace. This guide provides steps for installation, testing, and other important considerations. 😊

Prerequisites

Before starting, please ensure:

  • You have created a ShipperHQ account at ShipperHQ.com.
  • Within the ShipperHQ dashboard under Websites, you have created a new website and obtained an API Key and Authentication Code. Note the Scope your website is configured under, located in the top right corner of the dashboard. These credentials connect ShipperHQ to the cartridge.
  • Download the ShipperHQ cartridge ZIP file from GitHub.com.

Steps to Import the Cartridge

  1. Inside the ZIP, locate the int_shipperhq directory containing the cartridge, and install the int_shipperhq_sfra cartridge code.
  2. Update your site’s package.json to include the cartridge by adding "&& sgmf-scripts --uploadCartridge intshipperhqsfra" to "uploadCartridge".
  3. In Business Manager, navigate to Administration > Sites > Manage Sites > Business Manager Site. In the Settings tab, prepend "intshipperhqsfra:" to the beginning of the "Cartridges" path.
  4. Repeat the above step for each site under Administration > Sites > Manage Sites, accessing each site's Settings tab.

Steps to Import Meta Data, Jobs, and Services

The ShipperHQ cartridge uses product metadata and synchronization jobs, which need importing:

  1. Locate the metadata directory within the ShipperHQ cartridge folder.
  2. In the "jobs.xml" file, update the "site-id" attribute of the <context> tags, and adjust the WorkingFolder and ArchiveFolder parameters to match your Site ID.
  3. Compress the metadata directory into a ZIP file called metadata.zip.
  4. In Business Manager, go to Administration > Site Development > Import & Export. Click “Upload” under "Import & Export Files," select the ZIP file, and click “Upload”.
  5. Click “Import” and, upon completion, proceed to the next step.

Steps to Connect to ShipperHQ

Connect to ShipperHQ’s API using the Site Preferences:

  1. In Business Manager, go to Merchant Tools > Site Preferences > Custom Preferences and select the “ShipperHQ” group.
  2. Set “Enable” to “Yes.” Match “Scope” with your website's scope in the ShipperHQ dashboard (see Prerequisites).
  3. Enter the API Key and Authentication Code from ShipperHQ in the respective fields.
  4. Save these settings.

Steps to Synchronize Shipping Methods

To provide real-time shipping rates and options, pre-populate available shipping methods:

  1. Under Business Manager > Administration > Operations > Jobs, select “ShipperHQ”.
  2. Click “Run Now” to initiate synchronization.
  3. This syncs ShipperHQ's methods into Commerce Cloud.
  4. Confirm imported methods under Business Manager > Merchant Tools > Ordering > Shipping Methods.
  5. You can reorder methods; future syncs will honor this order.
  6. Rerun whenever new methods are enabled in your ShipperHQ dashboard.

Steps to Configure Product Attributes

To maximize ShipperHQ’s functionality, set additional product attributes:

  1. Go to Business Manager > Administration > Site Development > System Object Types > Product > Attribute Definitions.
  2. Locate “shipperHQDimGroups,” “shipperHQShippingGroups,” or “shipperHQWarehouses.”
  3. Ensure values correspond to your ShipperHQ configuration, such as Shipping Groups named “Large,” “Medium,” and “Small.”
  4. Apply changes, and proceed to set up the next attribute. Repeat for all necessary attributes.

Steps to Configure Products

  1. In Business Manager, go to Merchant Tools > Products and Catalogs > Products, select a product, and edit.
  2. Configure product attributes in the ShipperHQ section:
    • Assign “Origin Warehouse(s)” for multiple location fulfillment.
    • Enter "HS Code" for international shipping.
    • Set dimensions like “Ship Length,” “Ship Height,” and “Ship Width.”
    • Use “Fixed Shipping Fee” if a fixed price is applicable.
    • Assign “Shipping Groups” and “Dimensional Rule Group(s)” as needed.
  3. Only "Ship Weight" is required; all other fields are optional. 💡

Steps for Custom Code

No custom code is necessary. ✅

External Interfaces

Shipping rate requests are made to ShipperHQ at api.shipperhq.com over HTTPS, including:

  • Requests for the ship-to address and shipping-related attributes.
  • Responses listing available services and rates, which may optionally include delivery dates.

Firewall Requirements

Ensure outbound requests via port 443 to api.shipperhq.com are allowed.

Testing

Connect to ShipperHQ and Synchronize Shipping Methods

  1. In the ShipperHQ dashboard, under Websites, edit your site and copy the API Key. Click “Generate New Authentication Code,” confirm, and copy the Authentication Code.
  2. In Business Manager, under Merchant Tools > Site Preferences > Custom Preferences, select the "ShipperHQ" group.
  3. Set “Enable” to “Yes,” and match the “Scope” with your website’s scope.
  4. Enter the API Key and Authentication Code.
  5. Save these settings.
  6. Under Business Manager > Operations > Jobs, select “ShipperHQ.”
  7. Click “Run Now” to synchronize.
  8. Confirm shipping methods under Merchant Tools > Ordering > Shipping Methods. Ensure they match those configured in your ShipperHQ dashboard.

Set Product Attributes and Test Rating

  1. In Business Manager, under Merchant Tools > Products and Catalogs > Products, select a product and edit.
  2. Lock the product to enable editing and enter a value for “Ship Weight.”
  3. Save and unlock the product.
  4. On the Commerce Cloud site, add this product to your cart.
  5. Proceed to checkout and enter your shipping address. Rates will be retrieved from ShipperHQ.

Operations and Maintenance

Data Storage

The cartridge does not store any data.

Availability

ShipperHQ maintains over 99.96% annual uptime. We notify clients of expected maintenance or system impacts. Support is available 24/7/365 via email and phone 📞.

Failover/Recovery Process

Keep basic Commerce Cloud shipping methods configured but disabled, enabling them only if ShipperHQ is unavailable. Notify ShipperHQ during outages, and disable these methods once restored.

Support

Contact the ShipperHQ support team at support@shipperhq.com or call +1 (512) 215-4900 or +44 (0)1722 446240. Support is available during business hours, with critical issue support provided on weekends and holidays via email or voicemail.

User Guide

Roles, Responsibilities

The store admin must follow these instructions to install and configure the ShipperHQ cartridge:

  1. Update product attributes like Shipping Group or Origin as new products are added.
  2. Run the ShipperHQ synchronization Job to update Commerce Cloud with new services.
  3. Create shipping methods manually if using method merging, as the Job does not import merge codes.

Storefront Functionality

The cartridge does not introduce new storefront features.

Considerations

If a customer receives shipping rates during checkout but then alters their cart, the previously calculated rates remain visible. ⚠️