Written by Valérie Isaksen on .

Buy here in store!

USPS is the acronym for United States Postal Service, the postal service of United States government. This tutorial is a step by step tutorial for the USPS plugin.


Install the USPS shipment plugin

Install the USPS shipment plugin via the Joomla installer, and enable it.

Open a USPS account

To request access to the USPS production API, use the form here:

and ask to activate your account on the production server.

You will receive an email with the registration informations, and with your username.  This username is needed to configure your USPS plugin.

Test server: the USPS shipment plugin does not work on USPS test server. If your USPS account is not in a production mode, you will get this error message:

Error : USPS was not able to process the Shipping Rate Request.
Error Code: 80040b1a
Error Description: Authorization failure. You are not authorized to connect to this server.

In this case, contact USPS and request that your account is converted to production.

Create a USPS shipment method in VirtueMart

  1. From the VirtueMart administration, choose the menu Shop > Shipment methods
  2. Choose the New button
  3. Enter a shipment name. It is title that will appear on your web site.
  4. In the select list Shipment Method, select Vm Shipment - USPS
  5. Click Save

Configure the USPS shipment method

  1. Click on the configuration tab to configure your shipment method
    • Enter the Username of your USPS account
    • Unless you have a Proxy server, you don't need to enter this parameter.
    • Machinable packages
      • Select Yes if your package can be processed by a machine, 
      • Select No if it must be processed manually.
    • Package Size: select the option that describes the typical size of the package shipped from your store.
    • Weight Padding
    • Send dimensions: For every type of mail, there’s a minimum and maximum size. 
      This parameter forces the USPS shipment plugin to send Length/Width/Height information when requesting for rates when the Package Size is set to Regular. When the Package size is set to Large, the dimensions are always sent.
    • USPS Error Report : displays the errors returned by USPS. It is recommended to set to Yes. For example, if the client enters an unknown ZIP code, the message will be displayed:
      USPS error report example
    • Domestic Service Options: All the available services offered by USPS are listed. Select those you want to use. List of the Domestic USPS Services.
    • Domestic Countries list: select the countries
    • Domestic Handling Fee: this fee is an additional charge to be added to the shipping cost. It is an optional parameter.
    • International Services Options All the available services offered by USPS for international shippping are listed. Select those you want to use. List of the International USPS Services.
    • Countries: select the destination countries you want to ship to with USPS
    • International Handling Fee
  6. VirtueMart parameters
    • Logo: you can upload a logo via the Joomla Media manager in the folder images/stories/virtuemart/shipment. The list of the
    • Tax: you can apply a tax to your fee. The taxes are created via the menu "Calculation and tax rules".

Verifying Shipping Rates

The USPS Postage Price Calculator is a tool that helps you to verfiy the shipping rates. When comparing shipment charges between plugin and the USPS online calculator tool providing the rates, be sure that the requests are identical.

Trouble shooting

Q: We are sorry, no shipment method matches the characteristics of your order.
Reason 1: Most of the time, the reason for that message is a wrong Domestic Service Options configuration or International Services Options configuration. To check that this the reason, log in as vendor on the front end, and do a checkout. The following message will be displayed, followed by the delivery Services actually returned by UPS, and the delivery services that you have configurated in your shipment method. 

Info: USPS: The delivery services configurated in the shipment method do no match the Delivery Services returned by USPS.

If they do not match, then no shipment is listed. 


Reason 2: Another possible error is that you have entered a value for the parameter Proxy Server, and in your case it is not necessary. Leave blank that parameter, and try again.


Reason 3Your products do not have weight. IN this case, the plugin do not request quotes to USPS.



Q: Usps Response Error Usps Code -2147218040 Description The country name is a US Possession.

A: In the list of the  International country, you have selected one US country. Remove all US country from this list.

Q: Usps Response Error Usps Code 80040b1a Description Authorization failure. You are not authorized to connect to this server.

A: Most of the time this error occurs because the USPS account has not been activated by USPS. Follow the procedures in the email , and email their support group and request that your ID be converted to production.

Usefull links

We use cookies on our website. Some of them are essential for the operation of the site, while others help us to improve this site and the user experience (tracking cookies). You can decide for yourself whether you want to allow cookies or not. Please note that if you reject them, you may not be able to use all the functionalities of the site.