Skip to main content


Is the data for past orders available via the Insights API?โ€‹

No, ShipperHQ does not store shipment data until the Shipping Insights Advanced Feature is enabled. To enable it you will have to accept the term of services related to the storage of the Insights information by ShipperHQ.

Orders placed before this feature is active will not be available via Insights API. Additionally, if the Shipping Insights feature is disabled, no shipment information will be stored until it is reenabled.

Why is the data for a specific order not available via the Insights API?โ€‹

There are several reasons that a specific order may not be be available via the Insights API. This includes the order being placed before the Shipping Insights Advanced Feature was enabled, a mismatch between the website used for the order and the one being used to request the order, etc. More information is available in our Troubleshooting Shipping Insights documentation.

How do I know what value to populate for orderNumber?โ€‹

The orderNumber field is used to look up a unique order with the Insights API. If you are using the native ShipperHQ apps/plugins/extensions for supported eCommerce platforms (complete list here), the orderNumber will be the Order Number set by your eCommerce platform. If you are instead using the PlaceOrder mutation of the Labels API, orderNumber will be the value you set as the Order Number in your PlaceOrder call.

Is it possible to reuse Order Numbers?โ€‹

Each Order Number (used in the orderNumber field) must be unique to a specific Website configured in ShipperHQ. This means that it is possible to reuse an Order Number only on separate Websites (whether on the same ShipperHQ account or on separate accounts). For example, if you have a dev site connected to the same ShipperHQ account as your production site, you would need to ensure you have separate Websites configured in ShipperHQ for each to avoid duplicate entries for the same Order Number.

What are possible error codes and messages?โ€‹

If ShipperHQ encounters an error processing a Rate API request or if the ShipperHQ account is configured to prevent shipping in a given scenario, the Rate API will return an error object with an errorCode and associated internalErrorMessage. Possible errors are described below.

These errors can be categorized into several types:

  • Auth: Indicate issues with the credentials used. Ensure your credentials are accurate and not expired, that your ShipperHQ account is active, and that the Environment Scope in use is correct.
  • General: Indicate that ShipperHQ was unable to successfully process the request. If you encounter this type of error, confirm that your request is valid first and if so contact Dev Support.
  • Request: Indicate an issue with the format of an API request or the data it contains. Corrected by ensuring the request is formatted correctly and verifying the data in your request is accurate. For example, that the correct country or state/province/region codes are being used.
  • Account: Indicate an issue with the ShipperHQ account configuration. For example, that the Origin being used has an invalid address. Corrected by making the required adjustments to your ShipperHQ account.
  • Carrier: Indicate that ShipperHQ was unable to return results from a specific carrier. This may be intentional (e.g. error 304 indicates that the carrier is configured in ShipperHQ to explicitly not be allowed for a certain country) or unintentional (e.g. errors 305, 306, and 307 indicate that the request did not include information which is required by that carrier to return results). These errors may also mean that the carrier's API was unavailable when the request was attempted.

Error codes & messagesโ€‹

Error CodeTypeError Message
1GeneralRequest Error. There was an error processing your request.
3AuthInvalid Credentials. The credentials you supplied are invalid.
4GeneralInternal server error. We have been notified of this issue.
5GeneralService Unavailable. The service is currently unavailable. Please try again later.
6GeneralAccess Not Allowed. This host is not permitted to access this service.
7RequestMalformed Request. The request was not formed correctly.
8AuthAccess to the webservice has been disabled for this account.
300AccountInvalid Origin Country. The origin country is invalid
301AccountInvalid Origin State. The origin state cannot be found.
302RequestInvalid Destination Country. The destination country cannot be found.
303RequestInvalid Destination State. The destination state cannot be found.
304CarrierDisallowed Destination Country. The destination country is not allowed by this carrier.
305CarrierCarrier requires Country and/or State one of which is missing.
306CarrierCarrier requires City which is missing.
307CarrierCarrier requires zipcode which is missing.
308RequestDimensions on products are required.
309RequestWeight is required on all products for this carrier.
400AuthInvalid Environment Scope. The environmentScope is not found for this user.
401AuthWebsite not in Environment Scope. The web site does not exists in this environment scope
500CarrierNo shipping methods found for carrier. The system could not find a shipping method for the carrier.
402AccountNo origins have been set up for this website.
403AccountNo carriers have been setup for this origin.
404AccountNo merged rates. Please review your carrier mappings.
501CarrierCarrier Connection Error. Could not connect to carrier service for rates. Their system is possibly down.
502CarrierMax Weight Exceeded for Carrier. The maximum configured weight for this carrier has been exceeded. Change in carrier dashboard if wanting to increase.
503CarrierNo Pickup Locations Found. Could not find any pickup locations for this carrier.
504AccountGoogle API Key not present. Please set Google API Key in Global Settings on ShipperHQ Dashboard
505CarrierUnknown Carrier Error. No rates available
506CarrierCarrier returned error
507CarrierNo Valid Dates found for Carrier
508CarrierNo Valid Rates found for Carrier
509CarrierMax Packages Exceeded for Carrier. The maximum number of packages for this carrier has been exceeded.
510AccountCould not find carrier you requested
512CarrierMissing credentials for carrier.
600AccountShipping is prevented by a user defined rule. The merchant has used Carrier Rule to prevent shipping.
601CarrierShipping rates removed due to priority carrier returning rates.
700AccountMissing rates for carrier groups. Unable to find rates for all of the carrier groups.
800AccountThis account does not permit address validation
801AccountAddress validation is not enabled.