USPS Shipping Method

USPS Shipping is a premium method that sources shipping rates from the USPS API and works with our free service WooCommerce Shipping, which creates discounted shipping labels right from your WooCommerce dashboard.

USPS can calculate domestic and international parcel rates. This extension uses these USPS rates.

The API and built-in box packer need your non-virtual products to have weights and dimensions set. More info at: Adding Shipping Dimensions to Products.

• Your store must use US Dollars as its currency
• Server must have SimpleXML installed. Check with your hosting company if you’re unsure
• Base country must be the United States, Puerto Rico or US Virgin Islands

The extension primarily works with measurements in Inches (in) and weight in Pounds (lbs), but other units can be converted automatically.

1. Download the extension from your WooCommerce dashboard.
2. Go to Plugins > Add New > Upload and select the ZIP file you just downloaded.
3. Install Now, and then Activate.

The USPS Shipping Method extension requires a USPS Web Tools API account to provide live rates to shoppers. Please follow the instructions below to set up an account and request API access.

1. Register for a USPS Web Tools API Account:
   • Register for the legacy Web Tools APIs on the USPS.com Web Tools Portal.
   • After creating your Web Tools account, you will receive an ‘Important USPS Web Tools Registration Notice’ email from USPS with your new Web Tools USER ID and Web Tools Password. These credentials are only applicable to the Web Tools APIs, which is what the the USPS Shipping Method plugin uses.
   • Once you have your Web Tools USER ID from the registration email, add it to the USPS User ID field in the plugin settings on the WooCommerce > Settings > Shipping > USPS page. Only the User ID is required, so you don’t need to enter the password in the plugin settings.
   • Because USPS doesn’t automatically provide API access to new Web Tools accounts, there is one more step to complete before shipping rates will work on your site: You need to send an email to USPS and ask them to grant access to specific APIs to your new Web Tools account, as explained in the next step below.
2. Request API Access and Permissions:
   • After completing the registration steps detailed above, there is one more step that needs to be done before shipping rates will work on your site, which is sending an email to USPS and requesting access to the Rate Calculator APIs used by the USPS Shipping Method plugin, which are the following:
     • RateV4
     • IntlRateV2
   • If you attempt to use USPS’s API before access has been manually granted by them, the API requests will fail and you’ll see an error in the API response that says: API Authorization failure. User [USPS User ID] is not authorized to use API RateV4. However, this error will be resolved once API access has been granted.
   • The request process is outlined in registration email you received from USPS and detailed below:
     • The email should sent to webtools@usps.gov.
     • The email subject should be “Web Tools API Access Request”.
     • For the body of your of your email, include the following info:
       • Your Web Tools USER ID. This is a 12 or 13-digit, alpha-numeric ID that is created by USPS and included in the registration email they send after you create your Web Tools account.
       • Your USPS Mailer ID (MID). This mailer identification number is a 6 or 9-digit number assigned through the USPS Business Customer Gateway (BCG). If you don’t have one, you can put “I am a WooCommerce merchant and do not have my own Mailer ID”.
       • Your Company Website URL (ex: www.sitename.com).
       • List the API(s) for which you are requesting access: “The Rate Calculator APIs (RateV4 and IntlRateV2)”.
       • Expected volume (i.e., peak daily, weekly, monthly, etc.) per API. If you aren’t sure what your API request volume is, you can just put “Not known”.
       • Are you a shipper or software provider? “Shipper. Our business will be using the Web Tools Rate Calculator APIs to display USPS rates at checkout to customers in our ecommerce shop.”
       • Third-party software/software provider: “WooCommerce”.
     • Below is a pre-formatted response for the body of the API request email, which you can copy/paste into the email you send to USPS. You just need to add your Web Tools USER ID, the URL of your Company Website, and your Expected volume (if known):
       

Web Tools USER ID:

USPS Mailer ID: I am a WooCommerce merchant and do not have my own Mailer ID.

Company Website:

List the API(s) for which you are requesting access: The Rate Calculator APIs (RateV4 and IntlRateV2).

Expected volume:

Are you a shipper or software provider? Please provide details on how your business will use the APIs: Shipper. Our business will be using the Web Tools Rate Calculator APIs to display USPS rates at checkout to customers in our ecommerce shop.

Third-party software/software provider: WooCommerce

3. Configure the USPS Shipping Method in WooCommerce:
   • Once your account has API access, go to WooCommerce > Settings > Shipping > USPS on your site.
   • Insert your USPS User ID in the related field and configure the settings.
   • You are now ready to start using live rates!

Note: If you do not receive your welcome email within 24 hours, you can contact USPS API support via this form. For any questions or concerns regarding an access request contact webtools@usps.gov directly.

Go to WooCommerce > Settings > Shipping > USPS to enable debug mode and show on your cart and checkout pages the request the site sent to USPS and the response it got back. This information is shown only to administrators who are logged in, and it can be useful to understand why rates are or aren’t returned.

The Debug output is collapsed by default. Click on “USPS debug info” in the notification on the Cart or Checkout page to expand it, as seen in this example:

1. Go to WooCommerce > Settings > Shipping > Shipping zones.

2. Click the Edit button on the shipping zone where you want to offer this method.

3. Inside the shipping zone, click the Add shipping method button.

4. Then, select the shipping method and click the Continue button.

• Click the Edit button on the right side of the Shipping methods table to configure the settings:
  • Method Title – Name the shipping method. This is visible to customers.
  • Offer Rates – Choose whether to offer the customer only the cheapest rate or all returned rate options.
  • Fallback – Enter a fallback shipping cost (optional), if no rates are returned from the API. This allows the customer to check out if USPS does not return matching rates. When using this option, do not use a dollar sign, just enter the amount (ex: 12.50).
  • Flat Rates
    1. Flat Rate Boxes and Envelopes – Enable this option to offer shipping using USPS Flat Rate services. Items are packed into the boxes/envelopes, and the customer is offered a single rate.
    2. Express Flat Rate Title – Give a custom name to the express flat rate.
    3. Priority Flat Rate Title – Give a custom name to the priority flat rate.
    4. Additional Fee – Enter a fee per box excluding tax, such as an amount (2.50) or a percentage (5%). Or leave blank to disable.
  • API Rates – Check to enable non-flat rates using the USPS API. Default is all services available; or choose what to offer from the available shipping services listed below. You can adjust:
    1. Enable API Rates – This enables non-flat rate services.
    2. Origin Postcode – 5-digit postcode from where you ship. It is sent to the USPS AP (Note: ZIP+4 format is not supported and, if used, will return a Please enter a valid ZIP Code for the sender error).
    3. Shipping Rates – Retail rates are standard costs, Commercial rates are discounted. If you want those rates to match those you get when printing labels with WooCommerce Shipping, set it to “Commercial rates”. Printing with WooCommerce Shipping automatically qualifies you for Commercial rates.
    4. Parcel Packing Method – See below for more detailed explanation.

Note: The USPS shipping extension is a calculator for all products in the cart and does not exclude products based on shipping classes. To exclude products from using the USPS shipping method, use WooCommerce Conditional Shipping and Payments extension.

These services are included with the USPS Shipping extension:

• First-Class Mail® Large Envelope
• First-Class Mail® Postcards
• First-Class Mail® Stamped Letter
• First-Class™ Postcard Stamped
• First-Class™ Large Postcards
• First-Class™ Keys and IDs
• First-Class Mail® Metered Letter
• Ground Advantage™
• Priority Mail Express™
• Priority Mail Express™ Sunday/Holiday
• Media Mail®
• Library Mail
• Priority Mail®
• Priority Mail® Keys and IDs

• Priority Mail Express International™
• Priority Mail International®
• Global Express Guaranteed® (GXG)
• Global Express Guaranteed® Document
• Global Express Guaranteed® Non-Document Rectangular
• Global Express Guaranteed® Non-Document Non-Rectangular
• USPS GXG™ Envelope
• First-Class Package International Service^®
• First Class Mail® International Letters
• First Class Mail® International Large Envelope
• International Postcards

• Priority Mail Flat Rate™ – Envelopes (Legal, Letter, Gift Card, Padded, Small, Window) and Boxes (Small, Medium 1 and 2, Large, APO/DPO/FPO Large, Large Board Game, Prepaid Forever® Packaging)
• Priority Mail Express Flat Rate™ – Envelopes (Envelope, Legal, Padded) and Boxes (Top-Loading, Side-Loading)
• Priority Mail International Flat Rate® – Envelopes (Legal, Letter, Gift Card, Padded, Small, Window) and Boxes (Small, Medium 1 and 2, Large, APO/DPO/FPO Large, Large Board Game)

To enable any of these options:

Select the Standard Services option to ‘Retrieve Standard Service rates from the USPS API’.

You also have the option to rename the service and include a negative/positive price adjustment by the default currency or a percentage.

• Price adjustments ($) – Add a flat adjustment to the USPS service.
• Price adjustments (%) – Add a percentage adjustment to the USPS service.

If enabled, the flat rate box option creates a single quote based on USPS Flat Rate Services. To do this, the system uses the box packer (explained below) applying USPS box dimensions. Packed boxes are then combined to offer a single rate (named by your ‘method title’).

Flat Rate Shipping prices come directly from USPS, and you cannot add or modify pricing for this option.

In the case of both Flat Rates and API Rates are used, USPS will return both but will reject one in favor of the other if it is cheaper for the same service.

There are three packing methods with USPS, and each affects the parcels you send to the API.

Each item in your cart (non-virtual) is sent to the USPS API. Quotes for all items are combined to calculate the final cost.

Items are packed into pre-defined boxes and sent to the API. We recommend this option. See Box Packing below for more information.

Unpacked item handling – It’s possible that some items will stay unpacked because the available box(es) won’t fit them. It’s also possible that the item’s size or shape isn’t standard, preventing it from being combined with other items.

• Get a quote for the unpacked item by itself: This method gets the shipping cost for each unpacked item separately.
• Ignore the item – do not quote: The unpacked item is ignored in this option. However, you will receive quotes for the packed items.
• Use the Fallback Price: This option uses the Fallback price specified in the Rate Option Settings as a fallback.
• Abort – do not return any quotes for the standard services: This option does not give any quotes. You won’t even receive the quotations that are returned based on the customized Box Dimension.

Regular sized items (< 12 inches) are grouped and quoted for weights only. Large items ( > 12 inches) are quoted individually.

The box packer included with this shipping method lets you group items into packages for which you define height, width, length, weight and max-weight. You have two box packing modes to choose from in WooCommerce > Settings > Shipping > USPS: the Legacy packer (the default option) which is volume based, and the Enhanced packer that considers volume and item size.

The Enhanced packer should provide better results in most cases, but either option isn’t as accurate as a real person packing a box (see BIN Packing Problem). Therefore, it is important to understand that packing results are as accurate as possible, and any anomalies should be acceptable.

When using the ‘Recommended: Pack into boxes with weights and dimensions’ Parcel Packing Method, the Box Sizes table will appear. Click ‘Add Box’ to set up dimensions for your packages.

Name: This allows you to name your custom packages. This name will show in the Debug if that package is used.

L (in), W (in), H (in): The first set of dimensions are the outer dimensions of the package. These are the dimensions passed to the API. If you are working with a flat rate box via the API, use the API’s ‘inner dimensions’ for your box’s outer dimensions. Your box must ‘fit’ inside.

Inner L (in), Inner W (in), Inner H (in): The second set of dimensions are for the inner dimensions of the packaging. This should be the outer dimensions minus the thickness of the package walls. These dimensions are used for packing and items must fit within them (they cannot be the same size as the products, allow for a little extra room). Inner dimensions must be smaller than the first set of dimensions (outer dimensions).

Weight of Box (lbs): This is the weight of the empty box by itself. This weight is added to the total weight of the contents.

Max Weight (lbs): This is the maximum weight your box can hold. This includes the weight of the box and the contents. (Note: This value should never be set to 0 , as that will result in that box not being used due to the Max Weight limitation being met before any items are packed inside.)

Letter: This checkbox determines whether your package is a letter (envelope) or a box.

The box packer:

1. Finds boxes that fit items being packed (uses H x W x D).
2. Packs all items into boxes (using volume).
3. Uses the smallest box fitting 100% of items *or* uses the highest % packed box, and then passes unpacked items back (and repeats the process)
4. Packs unpackable items alone, using item dimensions.
5. Returns all packed boxes.

To enable Media Mail®, you must select the ‘Retrieve Standard Service rates from the USPS API’ option. You then have two options: a) You can do nothing, which allows any item to use Media Mail®; or b) if only some of your products are eligible for Media Mail®, you need to give each product a shipping class and restrict Media Mail® to use only that class or classes.

After setting up shipping classes, you can restrict settings in your Shipping Zone USPS rate:

Customers can get quotes based on the address entered from two places:

• Cart page – by using the shipping calculator
• Checkout page – by filling in shipping and billing forms

USPS has a straightward API, this issue doesn’t tend to show up as a result of API errors.

All shipping rates are live from USPS, so there is something in the request that is being made, and/or their response that is not matching up with their expectations.

• Shipping Zones may be set up incorrectly. Check the address matches a shipping zone. You can enable Shipping Debug under WooCommerce > Settings > Shipping > Shipping options.
• Enable debug mode to see debugging info on the cart page. This often reveals the issue. To enable, go to WooCommerce > Settings > Shipping > USPS.
• Check that products have sizes and weights set – without this, the calculation cannot be performed. Take a look at our documentation for adding weight and dimensions to products.
• Go to: WooCommerce > Settings > General and check that your store’s base country is the United States and US Dollars is the currency.
• Check that the plugin is linked to USPS API. It uses wp_remote_post, which makes use of fsockopen/CURL.
• If API rate are enabled, make sure origin postcode is included.

The returned rates are too high

Check the Shipping Rates section – Commercial rates are cheaper.

Enable Debug mode under WooCommerce > Settings > Shipping > USPS and visit the cart/checkout page. Check:

• Request includes the right product dimensions
• Rates being returned are the ones expected. For example “First-Class Mail®” could be one of 10 different types of First-Class Mail®
• Check the parcel packing method. Packing individually usually results in higher costs.
• Compare debug request to the USPS price calculator to confirm the different rates.
• Check the Price Adjustment columns to see if the user is adjusting the returned price.
• If you are using Flat Rates, these value are hardcoded into the plugin and it’s possible our plugin is out of date. You can compare the prices being returned here: http://pe.usps.com/text/dmm300/Notice123.htm

The USPS shipping method is only available to some users, not all, on my site

In this case, you might be using a plugin such as Role-Based Shipping / Payment Methods extension. It gives site administrators the ability to individually limit available Shipping Methods and Payment Gateways for each user role, including guests. As a result, we often find that USPS is disabled for some users in the Role-Based Shipping settings.

First-Class Mail International Large Envelope rate is not being returned

Currently, in order to have this rate returned on the user’s site, a custom box matching the size of the Large Envelope needs to be created and marked as a Letter:

If packing items individually, please note the minimum size requirements for the contents of a letter envelope:

If the contents of the envelope(the product in the cart) are not within the minimum and maximum dimensions shown above, the Stamped Letter service will not be shown as available.

If the Debug output shows API Authorization failure. User [USPS User ID] is not authorized to use API RateV4. in the “USPS Rate Response” section, you will need to contact USPS and request access to their RateV4 and IntlRateV2 APIs, as outlined in the Request API Access and Permissions section of this doc.

If you receive this error message when the debug mode is enabled, you need to use a shorter username.

Customizations are not covered under our support policy, so this isn’t something we can help implement or troubleshoot on your site.

To change the USPS package to envelope so dimensions are fixed, add this to your theme’s functions.php file:

/**
 * USPS 4.0 introduced the ability for envelopes to be flexible you can disable this with this function
 * Simply set the type to 'envelope' instead of 'package' for any of the flat rate services that USPS lists as envelopes
 */

add_filter( 'wc_usps_flat_rate_boxes', 'custom_usps_flat_rate_boxes' );
function custom_usps_flat_rate_boxes( $flat_rate_boxes ) {
    
    // Priority Mail Express Envelopes
    $flat_rate_boxes["d13"]["type"] = 'envelope';
    $flat_rate_boxes["d30"]["type"] = 'envelope';
    $flat_rate_boxes["d55"]["type"] = 'envelope';
    $flat_rate_boxes["d63"]["type"] = 'envelope';
    $flat_rate_boxes["d98"]["type"] = 'envelope';
    
    // Priority Mail Envelopes
    $flat_rate_boxes["d16"]["type"] = 'envelope';
    $flat_rate_boxes["d29"]["type"] = 'envelope';
    $flat_rate_boxes["d38"]["type"] = 'envelope';
    $flat_rate_boxes["d40"]["type"] = 'envelope';
    $flat_rate_boxes["d42"]["type"] = 'envelope';
    $flat_rate_boxes["d44"]["type"] = 'envelope';
    
    // International Priority Mail Express
    $flat_rate_boxes["i13"]["type"] = 'envelope';
    $flat_rate_boxes["130"]["type"] = 'envelope';
    
    // International Priority Mail
    $flat_rate_boxes["i8"]["type"]  = 'envelope';
    $flat_rate_boxes["i29"]["type"] = 'envelope';

    return $flat_rate_boxes;

}

To remove all the USPS Priority Flat Rate envelopes, leaving only the Small, Medium, and Large Flat Rate boxes, add this to your theme’s functions.php file:

/**
 * Remove USPS Flat rate envelopes from the available options
 * Once added the customer will not see any rates for envelopes
 * Only Small, Medium, and Large Flat Rate boxes will be used
 */
add_filter( 'wc_usps_flat_rate_boxes', 'custom_usps_flat_rate_boxes' );
function custom_usps_flat_rate_boxes( $flat_rate_boxes ) {

	unset($flat_rate_boxes["d29"]);
	unset($flat_rate_boxes["d30"]);
	unset($flat_rate_boxes["d63"]);
	unset($flat_rate_boxes["d16"]);
	unset($flat_rate_boxes["d38"]);
	unset($flat_rate_boxes["d40"]);
	unset($flat_rate_boxes["d42"]);
	unset($flat_rate_boxes["d44"]);
	unset($flat_rate_boxes["d13"]);

	unset($flat_rate_boxes["i33"]);
	unset($flat_rate_boxes["i30"]);
	unset($flat_rate_boxes["i63"]);
	unset($flat_rate_boxes["i8"]);
	unset($flat_rate_boxes["i29"]);
	unset($flat_rate_boxes["i13"]);

	return $flat_rate_boxes;

}

The codes for each flat rate box can be found below:

Priority Mail Express
Priority Mail Express Flat Rate Envelope: d13
Priority Mail Express Legal Flat Rate Envelope: d30
Priority Mail Express Padded Flat Rate Envelope: d63

Priority Mail
Priority Mail Flat Rate Envelope: d16
Priority Mail Flat Rate Medium Box (Side Loading): d17
Priority Mail Flat Rate Medium Box (Top Loading): d17b
Priority Mail Flat Rate Large Box: d22
Priority Mail Flat Rate Large Box (Board Game): d22a
Priority Mail Flat Rate Small Box: d28
Priority Mail Padded Flat Rate Envelope: d29
Priority Mail Gift Card Flat Rate Envelope: d38
Priority Mail Window Flat Rate Envelope: d40
Priority Mail Small Flat Rate Envelope: d42
Priority Mail Legal Flat Rate Envelope: d44

International Priority Mail Express
Priority Mail Express Flat Rate Envelope: i13
Priority Mail Express Legal Flat Rate Envelope: i30
Priority Mail Express Padded Flat Rate Envelope: i63

International Priority Mail
Priority Mail Flat Rate Envelope: i8
Priority Mail Padded Flat Rate Envelope: i29
Priority Mail Flat Rate Small Box: i16
Priority Mail Flat Rate Medium Box (Side Loading): i9
Priority Mail Flat Rate Medium Box (Top Loading): i9b
Priority Mail Flat Rate Large Box (Top Loading): i11

If you wish to exclude a country from receiving USPS rates, the easiest way is to use Shipping Zones. However if you wish, you can use the snippet below. Change US to the country code you’d like to exclude:

add_filter( 'woocommerce_package_rates', 'wcsupport_no_usps_us', 10, 2 );
function wcsupport_no_usps_us( $rates, $package ) {

  if ( WC()->customer->shipping_country == 'US' ) {
    foreach( $rates as $key => $rate ) {
      if (strpos($key,'usps') !== false) {
        unset( $rates[$key] );
      }
    }
  }
  
  return $rates;

}

You need to use the Recommended parcel packing method and ensure that the Letter checkbox is ticked:

Additionally, per USPS, these services are not offered because they can’t be used for shipping merchandise. However, there is a way to override this setting in the extension with the following snippet:

<?php

/**
 * Add letters and envelopes to international services.
 */
add_filter( 'wc_usps_services', function( $services ) {
    $services['I_FIRST_CLASS']['services']['13'] = "First Class Mail&#0174; International Letters";
    $services['I_FIRST_CLASS']['services']['14'] = "First Class Mail&#0174; International Large Envelope";

    return $services;
} );