USPS Shipping

USPS is a premium shipping method which let you get shipping rates from the USPS API. It requires that your store uses US Dollars for it’s currency and that your server has SimpleXML installed. The extension primarily works with in and lbs, but other units can be converted automatically.

USPS works with a base country of United States, Puerto Rico or the US Virgin Islands.

USPS can calculate quotes worldwide as it handles both domestic and international parcels.

The API, and the built in box-packer, require that your non-virtual products have weights and dimensions set. See here if you need to know how to do this.

Installation ↑ Back to Top

  1. Upload the plugin folder to the ‘/wp-content/plugins/’ directory.
  2. Activate the plugin through the ‘Plugins’ menu in WordPress.
  3. Thats it – you can now configure the plugin.

Video Overview ↑ Back to Top

Optionally you can watch the video below for a complete walkthrough of setting up USPS from beginning to end. It’s extremely detailed and quite long, so feel free to skip through it as needed but we’ve tried to explain most of the plugin setup in detail.

Configuration ↑ Back to Top

  1. Once the plugin has been activated, go to WooCommerce > Settings > Shipping.
  2. The method will be listed at the top of the screen, underneath the tabs. Click on ‘USPS’.
  3. You can now configure the method.
    1. Enable/Disable – Choose whether to enable the shipping method of not.
    2. Method Title - Name the shipping method. This will be visibile by customers.
    3. Origin Postcode – This should be set to the postcode from which you will ship. It is sent to the USPS API.
    4. Method Availability –  This setting lets you narrow down the countries which can get quotes. Leave set to All Countries to have it available for all customers.
    5. API Settings -
      1. USPS User ID – You can get your USPS User ID by signing up for a Webtools account on
      2. Debug Mode - Enable debug mode to show debugging information on your cart/checkout.
    6. Rates and Services - These settings control the services and rates you offer customers.
      1. Rates Options
        1. Shipping Rates – Choose the option you want to give to your customers: online services will normally be cheaper.
        2. Fallback – If not rates are returned from the API, optionally offer a fallback cost. Enter an amount here so the customer can still checkout if USPS does not return matching rates.
      2. Flat Rates - Enable this option to offer shipping using USPS Flat Rate boxes. See below for more details on this.
        1. Flat Rate Boxes and Envelopes – Enable this option to offer shipping using USPS Flat Rate services. Items will be packed into the boxes/envelopes and the customer will be offered a single rate from these.
        2. Express Flat Rate Service Name – Give a custom name to the express flat rate.
        3. Priority Flat Rate Service Name – Give a custom name to the priority flat rate.
        4. Flat Rate Fee – Enter a fee per-box excluding tax. Enter an amount, e.g. 2.50, or a percentage, e.g. 5%. Leave blank to disable.
      3. API Rates - Enable the non-flat rates using the USPS API. Choose the services you wish to offer. The default is that all services available will be offered. The available shipping services are listed below. The following aspects can be adjusted:
        1. Name – Add a custom name to the service package. Leave blank to use default name.
        2. Price adjustments ($) – Add a flat adjustment to the USPS service.
        3. Price adjustments (%) - Add a percentage adjustment to the USPS service.
Please note: The USPS shipping extension is a calculator for all products in the cart, and does not exclude products based on shipping classes.

Available Shipping Services for USPS Extension ↑ Back to Top

The following Services are included with the USPS Shipping Extension:

  • First-Class Mail® Parcel
  • First-Class™ Postcard Stamped
  • First-Class™ Large Postcards
  • First-Class™ Keys and IDs
  • First-Class™ Package Service
  • First-Class™ Package Service Hold For Pickup
  • Priority Mail Express™ Hold for Pickup
  • Priority Mail Express™ PO to Address
  • Priority Mail Express™ Sunday/Holiday
  • Standard Post™
  • Bound Printed Matter
  • Media Mail®
  • Library Mail
  • Priority Mail®
  • Priority Mail® Keys and IDs
  • Priority Mail® Regional Rate Box A
  • Priority Mail® Regional Rate Box B
  • Priority Mail® Regional Rate Box C

Flat Rate Shipping Options

  • Express Mail Flat Rate Envelope
  • Express Mail Legal Flat Rate Envelope
  • Express Mail Flat Rate Box
  • Express Mail Padded Flat Rate Envelope
  • Express Mail Padded Flat Rate Envelope
  • Priority Mail Flat Rate Medium Box
  • Priority Mail Flat Rate Medium Box
  • Priority Mail Flat Rate Large Box
  • Priority Mail Flat Rate Small Box
  • Priority Mail Flat Rate Small Box
  • Priority Mail Gift Card Flat Rate Envelope
  • Priority Mail Gift Card Flat Rate Envelope
  • Priority Mail Small Flat Rate Envelope
  • Priority Mail Legal Flat Rate Envelope
  • Priority Mail Flat Rate Envelope (International)
  • Priority Mail Flat Rate Small Box (International)
  • Priority Mail Flat Rate Medium Box (International)
  • Priority Mail Flat Rate Medium Box (International)
  • Priority Mail Flat Rate Large Box (International)


  • Priority Mail Express International™
  • Priority Mail International®
  • Global Express Guaranteed®
  • Global Express Guaranteed® Document used
  • Global Express Guaranteed® Non-Document Rectangular
  • Global Express Guaranteed® Non-Document Non-Rectangular
  • Global Express Guaranteed® Envelope
  • First Class Package Service™ International Letters
  • First Class Package Service™ International Flats
  • First Class Package Service™ International Parcel
  • International Postcards

To enable any of these options go to WooCommerce > Settings > Shipping > USPS to select the Standard Services option to ‘Enable Standard Services from the API’. From here you will have options to rename the service and include a price adjustment either positive or negative, by the default currency or a percentage.


Flat Rate Services ↑ Back to Top

If enabled, the flat rate box option will create a single quote made up entirely of USPS Flat Rate Services. To do this, the system will use the box packer (explained below) using USPS box dimensions. Packed boxes will then have their costs added together to offer a single rate (named by your ‘method title’).

It is important to note that the Flat Rate Shipping pricing comes directly from USPS API, and that you can not add additional pricing or modify pricing for this option at all.

Parcel Packing Method ↑ Back to Top

There are 2 packing methods with USPS; each affects the parcels you send to the API.


Each item in your cart (non virtual) will be sent to the USPS API. Quotes for all items will be combined for the final cost.

Pack into boxes

Items will be packed into pre-defined boxes and sent to the API. We recommend this option. See box-packing below for more information on this.

Box-Packing ↑ Back to Top

The box packer included with this shipping method lets you group items into packages of which you define the height, width, length, weight and max-weight. The packing is mainly volume based, but does also consider item sizes too.

The box packer is volume based. This will in most cases provide good results, but will never be as accurate as a real person packing a box (see BIN Packing Problem) therefore it is important you understand that packing results are as accurate as they can be and any anomalies should be accepted.

Setting up box sizes

Within the settings, look for the boxes setting. Click ‘add box’ to set up the boxes dimensions:

Box settings

Outer dimensions are used for parcel dimensions and are passed to the API. If you are working with a flat rate box via the API, for example Regional Boxes, use the API’s ‘inner dimensions’ for your boxes outer dimensions. You box must ‘fit’ inside.

Inner dimensions are used for packing, and items will be fit within these.

Box weight is the weight of the actual box, and will be added to the weight of the contents.

Max weight is the maximum weight your box can hold. This includes contents weight and box weight.

How the calculation works

The packer does the following:

  1. Finds boxes which fit the items being packed (uses H x W x D).
  2. Packs all fitting items into boxes (using volume).
  3. The largest box which fits 100% of items is used *or* use the highest % packed box, and then pass unpacked items back (and repeat the process)
  4. Unpackable items are packed alone, using the item dimensions.
  5. All packed boxes are returned.

Media Mail® ↑ Back to Top

To enable Media Mail® you must select the ‘Enable Standard Services from the API’ option. Once you do so you will have two options, you can do nothing which will allow any item to use Media Mail®, or if only some of your products are eligible for Media Mail® you’ll need to give each product a shipping class and restrict the Media Mail® to use only that class (or classes).

After you setup your shipping class you can find the restriction settings in WooCommerce > Settings > Shipping > USPS as shown in the screenshot here:


Customer Usage ↑ Back to Top

Customers will get quotes (after inputting their address) from two places;

  1. The cart page – by using the shipping calculator
  2. The checkout page – by filling in the shipping and billing forms
Rates can be selected by customers as normal.

Troubleshooting ↑ Back to Top

No rates returned/no rates available

  1. Enable debug mode to see debugging information on the cart page. This will often reveal the problem.
  2. Check your products have sizes and weights set – without this the calculation cannot be performed.
  3. Check your store’s base country is United States and that your using US Dollars (from WooCommerce > Settings > General).
  4. The plugin needs to be able to talk to USPS API. For this it uses wp_remote_post which makes use of fsockopen/CURL.

If you are not sure how to add weights/dimensions see the following doc:

Filtering Flat Rate Services

Change USPS package to envelope so that the dimensions are fixed, add to your theme functions.php file

Remove USPS Priority Flat Rate envelopes, add to your theme functions.php file

“UserName exceeds maximum length of 12 characters” error message

If you get the following error message when the debug mode is enabled, it means you need to use a shorter uername.

Back to the top