Argoworks Knowledge base/Magento/Magento FAQ

How do I set up USPS for shipping?

LightSpeed eCommerce Engineer
posted this on May 7, 2010, 17:08

This article assumes that you have already registered for USPS Web Tools here:

And have received confirmation from USPS that your account is active:


If you need to set up USPS or your customers are receiving this error on check out (See below) you should confirm the following

"This shipping method is currently unavailable. If you would like to ship using this shipping method, please contact us."

1. Confirm that our USPS API access is approved

2. Confirm that it is not in test mode and is in production mode

- If USPS says your account is active, this does not mean it is in production mode, - you need to call USPS and specifically request that it be moved to production mode after your account has been approved. A good idea is to perform this quick test:

Insert the following into your browser with your own USERID in place of the XXXX in the URL of any browser: USERID="XXXX"><FirmName>ABC Corp.</FirmName><SuiteOrApt>Suite 777</SuiteOrApt><Address2>1390 Market Street</Address2><Urbanization></Urbanization><City>Houston</City><State>TX</State><ZIP5>77058</ZIP5<ZIP4>1234</ZIP4></CarrierPickupAvailabilityRequest>

If your USPS account is active, it should accept the username.

3. Confirm that your username and password is for this site only.  USPS only allows 1 domain per account.

The most likely reason for this message is a problem with access to the USPS API. Magento, by default comes with the following URL set up in the shipping configuration for USPS:

Here is a working screenshot from a live Magento site using USPS:


The problem is that by default, you don’t have access to USPS’s production API. They have to approve you first. Keep in mind that they only allow you to use it on one web site per account, so if you’re setting Magento up for a client, customer, or other business entity other than your own you should set up a separate USPS account for them.

You can set up your USPS WebTools account here:

Once you have set up your account, they will give you access to the testing environment. The URL for the USPS test API is:

Now, before you paste that into Magento, you should be aware that the USPS test environment only supports very specific data. According to their own documentation:

ZipOrigination: 10022
ZipDestination: 20008 (is set during Checkout process by user)
Pounds: 10
Ounces: 5 (weight can be set for every product on Administration > Products)
Machinable: TRUE

To test international shipping use the following values:

Pounds: 2
Ounces: 0
MailType: Package
Country: Albania


Pounds: 0
Ounces: 1
MailType: Postcards or Aerogrammes
Country: Algeria

All other parameters’ values won’t work in the test environment.

We recommend asking USPS to turn on production mode. When you are approved by USPS for the production API, you should use the following URL:

But remember, it’s very important that you set up a separate USPS account for each Magento web site (or at least one per domain). USPS will disable your access to their production server if you are caught using your account on multiple web sites.

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 (Magento) and that you only want access to the API so that you can calculate shipping costs associated with using USPS.

If you leave out this information they will reject your request or ask you to submit a valid test before they give you access. 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)

Article content provided by Asher Bond