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

Managing ShipperHQ on Magento 1

Configure and maintain ShipperHQ on your Magento 1 store

Table of Contents


If you're running a Magento 1 store and depend on ShipperHQ for accurate shipping rates at checkout, this article covers what you need to update your configuration, troubleshoot, and maintain your setup. It also covers moving over from a legacy WebShopApps extension, if that's what your store still uses today.

Magento 1 reached end of life in mid-2020 and no longer receives official support or security patches from Adobe. ShipperHQ continues to function on Magento 1 for merchants running existing stores with official Adobe releases exclusively. We recommend that new stores be built on Magento 2 or another supported platform.

The original Magento 1 installation and customization articles are available as a PDF archive for reference. This content is no longer officially maintained or supported.


Configuration Reference

Once ShipperHQ is installed on your store, configuration options are located at System › Configuration › Shipping Methods › ShipperHQ.

Basic Configuration

  • API Key and Authentication Code — created in ShipperHQ under Websites, on the website set up for your store. These connect Magento to ShipperHQ and should match what's shown in your ShipperHQ dashboard. See How to Connect ShipperHQ to Your Website for details.
  • Environment Scope — should match your ShipperHQ environment scope setting.
  • Enabled — set to Yes for ShipperHQ to function as an active shipping method.
  • Other shipping methods in Magento should be disabled to prevent unexpected results at checkout.

Configuration Options

  • Main Shipping Carrier Title — carrier title displayed when no other carrier title is returned from ShipperHQ. Set this to something generic, like "Shipping Rates."
  • Environment Scope — the environment scope configured in your ShipperHQ dashboard.
  • API Key — the unique identifier in ShipperHQ for your website.
  • Authentication Code — the unique code that authenticates this website with ShipperHQ.
  • Backup Carrier/Method — a standard Magento shipping carrier that acts as a backup in the unlikely event that ShipperHQ doesn't respond.

Advanced Settings

  • Custom Shipping Rates in Admin — allows an admin user to manually enter a shipping rate for orders placed via the admin panel.
  • Hide Carrier Notifications at Checkout — hides additional carrier-provided information that would otherwise display alongside rates.
  • Display Transaction ID — ShipperHQ support may ask you to enable this to aid debugging.
  • Timeout (seconds) — how long to wait for ShipperHQ to return rates before calling the backup carrier.
  • Delivery Comments on Checkout — enables a comments field on the checkout shipping method page.
  • Enable Suburb Lookup — enables autocomplete for suburbs in supported countries during cart and checkout.
  • Maximum Number of Results — limits the number of shipping carriers displayed.

Sandbox Mode, Sandbox URL, Live URL, and Secure URL should not be edited unless ShipperHQ support advises you to do so.

If you previously configured Ship to Applicable Countries or Ship to Specific Countries, those settings remain visible for stores that already had them set. For new configuration, use ShipperHQ's Zones feature instead to control which countries are applicable.

Standard Shipping Options

  • Show Method if Not Applicable — displays a notification from ShipperHQ when no rates are returned.
  • Displayed Error Message — the text shown if ShipperHQ doesn't return a response.
  • Sort Order — the sort order of ShipperHQ rates within Magento.

Emailing Each Origin or Store Within an Order

You can configure ShipperHQ to have your Magento store send a transaction email to each origin or store within an order, sharing the details relevant to that origin. This is useful for merchants with multiple warehouses or store pickup locations who need each location notified about only its portion of an order.

In ShipperHQ, set the email address for each origin, and choose when to send it:

  • Never — email is disabled for that origin.
  • On Place Order — sent as soon as a new order is created.
  • On Create Invoice — sent as soon as an invoice is raised.

In Magento, create a new transactional email template using the New ShipperHQ Shipment template, then enable it under System › Configuration › Sales Emails › ShipperHQ Order Emails and select your new template as the New Order Confirmation Template.

Caching Rates for Better Performance

Enabling caching lets Magento reuse a previous ShipperHQ rate response when nothing about the request has changed, such as during a checkout refresh. This reduces load and speeds up checkout.

Go to System › Cache Management and enable the cache for Collections.


Troubleshooting Your Installation

If you're seeing incorrect shipping rates rather than an installation issue, see the Rate Discrepancies guide instead.

Blank or white page when navigating the store

This usually indicates a silent error. If Magento's compiler is enabled, refresh it.

"Method ... is not defined" error

This points to a file-reading issue. Re-copy all files from the installation ZIP, refresh the cache and compiler (if enabled), and confirm file permissions are set correctly on the server.

"Include file missing" warning

Refresh the Magento compiler if it's enabled.

"Website Not in Environment Scope"

This appears in System › Configuration › Shipping Methods after saving. It means ShipperHQ and Magento are looking at different scopes. Confirm the scope shown at the top right of your ShipperHQ dashboard matches the Environment Scope set in your Magento configuration.

Invalid credentials error

Verify that the API Key and Authentication Code match what's shown under your website's configuration in the ShipperHQ dashboard. See How to Connect ShipperHQ to Your Website for details.

SQL errors on install (e.g., "Base Table Or View Not Found")

This means the SQL install scripts didn't run successfully, often because of a conflicting core_resource entry left behind from a prior install attempt. Take a full database backup before attempting any of the options below.

Manually rewind core_resource:

  1. Locate the core_resource table.
  2. Find the entry causing the issue (for example, shipperhq_shipper_setup).
  3. Remove that entry.
  4. Turn off the cache.
  5. Refresh the frontend and confirm the install script now runs, creating the missing tables and attributes.

Using the delete/rewind script (recommended):

ShipperHQ provides a script to delete or rewind the core_resource entry. This requires the latest WSA Common installed.

Use this script only if you're confident in what you're doing; running it incorrectly can affect your installation.

  • To delete (first-time installs only): add the script to the base of your Magento install, navigate to your base Magento URL followed by /setResource.php, and select your extension from the dropdown (or enter the core_resource code manually, such as shipperhq_shipper_setup, if it's not listed). Click Show Current Resource Version, then delete. Refresh the frontend and confirm the attributes were created, then remove the script file when finished.
  • To rewind (roll back to an earlier version so Magento re-runs the upgrade script): follow the same steps, but note the module version to roll back to and click rewind instead of delete.

If problems persist, check the report in var/report for details, or contact ShipperHQ support with your error report and a description of the issue.

Logging and Diagnostics

If you need to troubleshoot a shipping rate issue or provide ShipperHQ support with diagnostic details, the WebShopApps Logger records information about each rate request and response.

To configure the Logger, go to System › WebShopApps Logger. Logging is disabled by default. If you see an Access Denied error, log out and back into the Magento admin.

Logging can be sent to the admin panel, the file system, or via email, and set to one of four levels (Critical, Warning, Info, Debug). In production, keep logging disabled to avoid unnecessary database or file system load.

Interpreting the Log Output

Each rate request log entry lists the items in the cart, including price, weight, quantity, and SKU, along with each item's attributes: shipping groups, dimensions, origin, and any other assigned attribute.

Finding Your Transaction ID

If ShipperHQ support asks for a Transaction ID to help diagnose a rate issue, you can find it two ways.

From the admin panel:

  1. Perform the request or test you're investigating.
  2. Go to System › WebShopApps View Logs.
  3. Open the Rate Request and Result log.
  4. Search the response for TransactionId using your browser's find function (Cmd+F or Ctrl+F).

From the storefront cart:

This method displays debug messages on the front end. It is not recommended for live stores.

  1. Go to System › Configuration › WebShopApps Logger.
  2. Set Show Debug Messages on Front End to Yes.
  3. Perform the request in the shopping cart (not checkout).
  4. The Transaction ID displays under the carrier title.

Copy the Transaction ID along with a description of your issue for ShipperHQ support. Afterward, turn the logger off and set Debug back to No to avoid slowing down rate requests.

Migrating From WebShopApps

If your Magento 1 store currently uses standalone WebShopApps extensions rather than ShipperHQ, this section covers moving over. ShipperHQ covers the functionality of WebShopApps' individual extensions in one unified platform, so we recommend migrating your WebShopApps extensions to ShipperHQ rather than running both side by side.

Before starting, back up your server files and database, and test the migration on a development or staging site first.

Installing ShipperHQ and Migrating Your Settings

  1. Unzip the ShipperHQ extension and navigate to app/etc/modules/.
  2. Set every ShipperHQ file in that directory to disabled, except Shipperhq_Shipper.xml.
  3. Install the ShipperHQ extension using the files you've unzipped.
  4. Migrate your existing WebShopApps attribute values into the new ShipperHQ product attributes this creates. See WebShopApps to ShipperHQ Attribute Mapping Reference (Magento 1) for details.
  5. Re-enable the ShipperHQ modules you disabled in step 2, then complete the remaining installation steps (enabling caching and recompiling, if applicable).

Test thoroughly and confirm rates are correct before disabling your WebShopApps extensions on a live site.

Disabling WebShopApps Extensions

Once you've confirmed ShipperHQ is returning correct rates, disable your WebShopApps extensions.

You can disable these without any extra steps:

  • Address Validation
  • Residential Selector
  • Delivery Options for UPS
  • Shipping Calendar
  • UPS Calendar
  • Store Pickup
  • Admin Shipping

The following require an extra step in the database before they can be disabled:

  • DropShip/Ship Manager — in the eav_attribute table, find the attribute with code warehouse and a source model referencing dropship. Set its source model to null.
  • Dimensional Shipping — find the attribute with code referencing shipping possible boxes and a source model referencing box menus. Set its source model to null.
  • Freight Shipping (ABF, Cerasis, Con-Way, CTS, Echo, Estes, FedEx, Old Dominion, ProStar, RL Freight, UPS Freight, YRC) — find the attribute with code referencing freight class, and set its source model to null. If your freight extension uses a dropdown to select freight class on the product and doesn't use this attribute code, follow the same pattern for its attribute; if it uses a plain text field instead, no attribute change is needed.

After the source model is cleared, follow the standard disable procedure above.

Dropcommon, Endicia, Handling Separate, and Product View Rates (prior to 1.11.6) currently have no documented disable procedure. The Support team can help if you have questions about disabling one of these.

Planning Your Move to Magento 2

Because Magento 1 is no longer supported by Adobe, moving to Magento 2 is worth planning for even if your current setup is stable. The file structures between the two platforms differ significantly, so a direct copy of your Magento 1 setup won't carry over.

Follow Magento's own migration guidance (Adobe) alongside these ShipperHQ-specific steps. This assumes familiarity with MySQL — adjust the queries below as needed for your database setup, and back up your database before running any DELETE or UPDATE statements.

  1. Follow the Disabling & Uninstalling the ShipperHQ Extension guide to remove the Magento 1 extension.
  2. Clean up the Core Config table. Run the SELECT first to confirm the values returned are accurate before running the DELETE:
    SELECT * FROM `core_config_data` WHERE `value` like '%shipperhq_shipper%' or `value` like '%shq%';

    DELETE FROM `core_config_data` WHERE `value` like '%shipperhq_shipper%' or `value` like '%shq%';
  3. Verify the Core Config table is clean:
    SELECT * FROM `core_config_data` WHERE `value` like '%shipperhq_shipper%' or `value` like '%shq%';
  4. Clear ShipperHQ references from product attributes so they don't conflict with the new Magento 2 installation:
    SELECT * FROM `eav_attribute` WHERE `source_model` like '%shipperhq%';

    UPDATE `eav_attribute` set `source_model` = '' WHERE `source_model` like '%shipperhq%';

     

  5. Follow the Magento 2 installation guide to install ShipperHQ on your new Magento 2 store.

FAQ

Why does "ShipperHQ" appear as the carrier name at checkout instead of the actual carrier?

The Main Shipping Carrier Title field defaults to "ShipperHQ" and displays when no specific carrier title is returned. Go to System › Configuration › Shipping Methods › ShipperHQ and update Main Shipping Carrier Title to a neutral label, such as "Shipping" or "Shipping Rates."


Additional Resources