How to set up Magento with USPS shipping methods and get permission to use the USPS production API

2011 Fresh update:

Many people don’t know the news… You can now subscribe to a low-cost, PCI and DSS compliant, managed version of Magento in the Cloud. It’s called Magento Go (formerly Magento Stratus when it was only a nascent release candidate). Along with this new Magento offering, Varien (Magento’s open-core contributor company) has announced a startup-friendly economic stimulus package (which is a freemium trial with no setup fees and deferred monthly recurring costs) to help you build e-commerce business momentum with little technical effort.

For those of you who are e-commerce systems integrators who like to get down into the nuts and bolts and those of you who just like to take e-commerce in-house… you may be getting the following error message when trying to integrate USPS shipping calculations:

United States Postal Service:
This shipping method is currently unavailable. If you would like to ship using this shipping method, please contact us.

The error is generally caused by one of these four issues:

  1. USPS hasn’t moved your new (test only) Webtools account into production.
  2. You didn’t specify the weight metrics for your product(s).
  3. You didn’t put in the correct web tools ID as your shipping methods user ID (should look like 123MYMAG4567 … or 6 dots when it’s saved)
  4. You forgot to put the http:// in your gateway URL (under shipping methods).

Magento, by default comes with the following URL set up in the shipping configuration for USPS:

If you put in the weight for each of your products and you are specifying the right production gateway (, then it’s likely that you don’t have access to USPS’s production API. USPS doesn’t give you access to the production API by default, but rather… they give you access to the test API which only supports one specific address. USPS needs to approve your account before they will give you access to the production USPS API. Once they transition your account into production, Magento should start working. 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.

If you 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 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.

This is why most Magento consultants and installation service providers typically just ask 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. That would make all of your Magento customers very upset, all at the same time.

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)

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 calcualted based on the weight of the product you are ordering.

You will need to remove shipping options that are irrelevant, for example USPS Library Mail is only for shipping academic things like books between academic institutions or libraries.

Click here to read about different shipping methods such as Parcel Post.

Click here to download premium themes for Magento, Joomla, WordPress, Drupal, PHPBB, etc.

Tagged with: , , , ,
Posted in eCommerce
43 comments on “How to set up Magento with USPS shipping methods and get permission to use the USPS production API
  1. Josh says:

    Thanks for this – it helped me greatly! I’m currently having an issue where multiple quantities on products cause the “…not available…” error message… any thoughts on why?

  2. Hi Asher!
    Many thanks – I actually have same problem with UPS. Can you post suitable links for UPS-API also?


    Rafael Kutscha

  3. Asher Bond says:

    I’m glad it was helpful. I’ll try to post instructions for UPS and Fedex next.

  4. Jack says:

    Hi Asher, I am having problem to test the USPS API. I have applied a USERID and is working fine.

    But when I try RateV3 and IntlRate it always give me a “API Authorization failure” failure. I followed your suggestion to use :

    Also tried domestical rate, all failed with same error.

    Could you tell me what I did wrong in my XML? I checked USPS site and didn’t find the document about testing parameters.

    Thanks for your help.


  5. Asher Bond says:


    Thanks for participating in my blog. Unfortunately the USPS testing API only tests that specific shipping data and price that I mentioned above. Once the “Albania” test works, they should give you access to everything else you need. Also, if you tell USPS that you are using an approved 3rd party software application they are familiar with (such as Magento) you don’t have to test it. I hope this helps.

    – Asher Bond

  6. Jack says:

    Thanks Asher. I was using the parameters you mentioned but it’s still not working for me for some reason:





    Not sure what I did wrong. the CityStateLookup Query is working fine. the url in my previous post was messed up.

    Yes I am using Magento, will try to turn on production to see if it work.


  7. Jack says:

    sorry the xml is messed up again, should be:

    <IntlRateRequest USERID="xxxxx">
    <Package ID="0">

    <RateV3Request USERID="xxx">
    <Package ID="1ST">
    <Service>FIRST CLASS</Service>

    please delete my post if you feel it messed up your blog.

  8. Asher Bond says:


    Try production mode if you are using a stable release of Magento. If you contact USPS at the link I provided and explain your situation, they will recognize Magento and probably grant you a production API key as long as you are using a stable version of Magento. Once you are in production mode, you can still test it by previewing right before you check out. It should show a preview of the calculated USPS shipping costs in Magento without actually executing an order transaction.

  9. jen says:

    suddenly today, the first class international stopped working? anyone else have this issue?

  10. W says:


    Yes! My shipping stopped 100% today. BAD!!!


  11. Hola!

    I received the mail, authorization to use the api (said he used magento)
    I try to configure the usps in magento but I can not select the shipping method
    and I still leave a message:

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

    thnxs 4 ur support

  12. Margo says:

    Thank you so much for this! I searched Magento’s support and forums everywhere and there was no mention of this requirement in order to get USPS quotes to work. And FedEx works without any such registration, so I couldn’t figure out what was wrong. Went through the hoops and it worked like a charm, THANK YOU 🙂

  13. Pit Silas says:

    Thanks for writing about this. There’s a heap of great tech info on the internet. You’ve got a lot of that info here on your site. I’m impressed – I try to keep a couple blogs somewhat live, but it’s a struggle sometimes. You’ve done a big job with this one. How do you do it?

  14. rakhi says:

    Hi Asher,
    I am integrating the USPS shipping method in magento, i am using the registered user id and also i tries by using the following gateway urls and also with but i am getting the following error message i.e. This shipping method is currently unavailable. If you would like to ship using this shipping method, please contact us.
    Please let me know which gate way url have to use.

  15. Bill says:

    I am having the same trouble… moved to production servers but still no luck. One thing, I received a user id that has both username and password… enter username in userid field in Magento? Thanks for this post Asher, apparently it is sorely needed!

  16. Bill says:

    Same trouble here, but it does not appear to be USPS. I have tried: Wildwood DriveOld LymeCT06371
    (a test string to the production servers from USPS documentation) and I get a valid response. If I change the “MYUSERID” to something other than mine, I get an authentication error. USPS appears to work.

    USPS is:
    Container: Variable
    Size: regular
    Machineable: Yes
    Max pkg wt: 70
    Handling Fee: Fixed,Per Order,4.00
    No Free method
    All Allowed Countries

    Not a lot to do here… any insight?

  17. Awesome post, I’m a huge fan of your blog, keep on writing these great posts, and I will be a regular visitor for a very long time.

  18. mike says:

    hi jack, very useful post. it helped me tremendously. i followed the steps and set up the usps api and my magento site is working fine now. i need to setup ups xml so it will do the same thing the usps is doing and also allow me to print out shipping labels. could u kindly help me or write an article about that too? there are lots of questions being asked about that on magento forums but there seems to be very little data to actually accomplish the task. please help if u can. thanks again.

  19. Sebbi says:

    Very helpful!! Saved me a lot of time! Thank you very much! I assume it’s basically the same process for FedEx or UPS…

  20. hrs says:

    Hi, You made some good points there. I did a search on the topic with google and found most people will agree with your blog.

  21. Kirk Kehrer says:

    I really enjoyed this article. Continue your cool work.

  22. In the relevant virtual host and host of the Linux program more specific site search, your site up.

  23. Asher Bond says:

    Thank you, relevance is often underrated… but not as often as Linux is underrated. What inspired you to register How do you decide if a toronto escort is ok or not?

  24. Annie says:

    Hello: We are trying to get USPS working for our magento install. Got the USERID/Password. Got production access from USPS. However, we are still getting the shipping method not available message.

    Could you possibly confirm whether we are supposed to enter the UserId or the password in magento. I am assuming userId, although I tried both. Are we supposed to do anything with the password in the magento configurations?


  25. Marius says:

    I’m having the same issue as Annie. I have been granted production api privileges, everything is entered into magento, yet I’m still getting the same error… only rate it shows is “Library Mail”…

  26. Mike Roth says:

    We are having a problem with USPS again. The last recorded order that used USPS as the shipping option went through on Feb. 28, 2011 and I noticed that USPS was not showing as a shipping option anymore on March 2nd, 2011. Some time in there it just stopped working.

    I am running version

    I noticed from other threads that go back to the beginning of 2011 there were people who had this problem. When I try to follow the steps they did to fix it it already looks like it has been done. I use to work with a programmer back then who might have done this for us. He is no longer around to ask him now 🙁

    Does anyone know what I should do to get this working again? Anyone else just get this problem happening recently?

  27. Has anyone figured out a solution? I have done everything noted in this thread but it still does not work. Please help if you can.



  28. AlexA says:

    Thanks so much, this was a great post. Keep up the good work!

  29. Aran says:

    @MikeRoth – check out this:

    Seems to be working for most people…

    I’m guessing this post is for people on CE 1.4.2 or higher?

  30. Matt says:

    Thank you very much. We can’t underestimate the change that setting certain MySQL variables can have on speed.

    Best wishes, Matt.

  31. vishnu says:

    hi Asher I just got a problem in magento was using nicely and ups was not charging correctly and i just add ups account detail and know it it not showing ups as shipping method plz reply fast

  32. vb says:

    UPDATED ( – not working anymore):

    When you have completed your testing, email the USPS Internet Customer Care Center (ICCC). They will switch your profile to allow you access to the production server and will provide you with the production URLs.

    The ICCC is staffed from 7:00AM to 11:00PM Eastern Time.

    Telephone: 1-800-344-7779

  33. Paracha says:

    How to set weight in testing

  34. brittney says:

    Question: what would cause the “shipping method not available” error for only a specific address, but work for others? Have you run into that?

    Thanks for your in-depth page info on setting this us – it helped us a ton!

  35. senthil says:

    hi i got username and password in my mail and how to proceed

  36. Johnny says:

    Such an excellent written report! No idea how you wrote this’d take me days. Well worth it though, I’d suspect. Have you considered selling ads on your website?

  37. Young Macanas says:

    thank’s for your article.

  38. Joyce says:

    Thanks for posting. Do you also have a solution to the same problem with UPS?

  39. James says:

    Oh, an excellent text! I have no clue how you managed to write this’d take me long hours. Well worth it though, I’d suspect. Have you considered selling advertising space on your website?

  40. gavin says:

    Thank you very much for this post, it helped me out tremendously.

  41. Zam Sham says:

    After 3 days of wrestling with this thing, I finally got it working. Thanks for the tips they were helpful.

    ***** ONE WORD OF CAUTION *****

    To everyone who followed the instructions and still having problems with it working make sure of the following…

    Check your gateway and secure URLs in the magento configurations (admin panel)


    After following the directions precisely, I found 1 empty space behind my Gateway URL and that was my problem the entire time!

    Hope this helps.

  42. Rustam says:

    Hi Asher,
    thank you for your “how do i set up usps for shipping? ” article. just one question please:
    do i have to setup a separate usps api accounts for each magento website or each magento store?
    because i have 1 website, but it’s bilingual magento website.
    thank you in advance.

2 Pings/Trackbacks for "How to set up Magento with USPS shipping methods and get permission to use the USPS production API"
  1. […] How to set up Magento with USPS shipping methods and get … […]

  2. How to set up Magento with USPS shipping methods and get permission to use the USPS production API | What web developer needs? says:

    […] Thanks for Asher Bond for nice advice […]