Recently, while setting up a client’s Magento ecommerce website, we ran into an issue with USPS. So I wanted to share with you how we were able to work around the problem and successfully set up Magento with USPS and get permission to use the USPS production API.
A common error message when trying to integrate USPS shipping calculations to a Magento site is:
This shipping method is currently unavailable. If you would like to ship using this shipping method, please contact us.
We found that the error is generally caused by one of these four issues:
- USPS hasn’t moved your new (test only) Webtools account into production.
- You didn’t specify the weight metrics for your product(s).
- You didn’t put in the correct USPS Web Tools ID as your shipping methods user ID (should look like 123ABCDE4567 [3 digit + 4 characters + 4 digits] or 6 dots when it’s saved in Magento).
- You forgot to put the https:// in your gateway URL (under shipping methods).
By default, Magento comes ready with two URLs in the shipping configuration for USPS:
If you enter the weight for each of your products AND you are specifying the right production gateway links (https://production.shippingapis.com/ShippingAPI.dll and https://secure.shippingapis.com/ShippingAPI.dll), then the likely problem is that you don’t have access to USPS’s production API. USPS doesn’t give you access to the production API by default, instead they give you access to the test API which only supports one specific address.
Before USPS will give you access to the production USPS API, they must first approve your account. Once they transition your account into production, Magento should start working automatically. *Keep in mind however that USPS only allows one website per account.
Don’t have a USPS API (WebTools) account? You can set up your USPS WebTools account here:
Once you have set up your account, they will grant you access to the testing environment. The URL for the USPS test API is:
NOTE: The USPS test environment only supports specific data. According to USPS documentation:
ZipDestination: 20008 (is set during Checkout process by user)
Ounces: 5 (weight can be set for every product on Administration > Products)
Machinable: TRUETo test international shipping use the following values:
Country: United States
MailType: Postcards or Aerogrammes
All other parameters’ values won’t work in the test environment.
This is why most Magento developers will typically just ask USPS to turn on production mode. Once approved by USPS for the production API, you should use the following URL:
REMINDER: It’s very important that you set up a separate USPS account for each Magento website you build. USPS will disable your access to their production server if you are caught using your account on multiple ecommerce websites.
To request access to the USPS production API, fill out the form here:
Be sure that in your request, you explain that you are using third party software (i.e. Magento) and that you only want access to the API so that you can calculate shipping costs. If you leave this information out USPS will reject your request. Third party software doesn’t need to be tested as long as you tell them you are using Magento.
USPS doesn’t allow you to use their API for batch processing or data cleansing, so be sure to NOT check these boxes on the request form.
Once USPS gives you access to their production API server, Magento should work with all USPS shipping options. If you are still having trouble, check that you have access to USPS’s production API server.
USPS Tech Support: 1-800-344-7779 (7:00 AM to 11:00 PM EST daily)
SIDE NOTE: We called USPS Tech Support and were surprised at how fast and helpful they were. It never took more than 5 minutes to turn a USPS API Key from test mode to production.
Once you have it correctly configured and you have access to the production API, you should be able to place an order and check out to see a list of USPS shipping options with the costs of each calculated based on the weight of the product you are ordering. You will need to remove shipping options that are irrelevant. USPS Library Mail, for example, is only for shipping academic things like books between academic institutions or libraries.