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.

Requirements

↑ Back to top

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

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

Installation

↑ Back to top

Install and activate USPS Shipping Method from WooCommerce > Extensions > My Subscriptions, or add it to your store from My subscriptions on WooCommerce.com. See Managing WooCommerce.com subscriptions for more installation options.

USPS Web Tools APIs are retired

↑ Back to top

USPS retired the legacy Web Tools APIs on January 25, 2026. The USPS Shipping Method uses the replacement REST API in version 5.2.5 and later.

What changed

• USPS retired the legacy Web Tools APIs on January 25, 2026.
• The USPS REST API replaced the legacy Web Tools APIs.

How this affects you

• REST API support is available in USPS Shipping Method version 5.2.5 and later.
• Sites that still use the legacy Web Tools connection may no longer receive live USPS rates.
• Switch to the REST API to restore live rate calculations.

What you should do

• Update the USPS Shipping Method to the latest version, then switch to the REST API. Version 5.2.5 is the minimum version that supports REST.
• Follow the instructions in the Generating Your REST API Keys section below to create the credentials needed to connect your USPS business account.
• Test the REST connection on a staging copy of your site before making the change on your live site.
• If USPS rates do not appear, enable Debug Mode and review the API response in the logs.
• Contact our support team if you run into problems switching to REST.

Connecting the API

↑ Back to top

USPS Shipping Method version 5.2.5 and later uses the USPS REST API. You need a USPS Business Account and an app created through USPS before you can connect the extension.

• Sites that still have a legacy Web Tools connection show the API Type setting on the WooCommerce > Settings > Shipping > USPS page. Select REST before adding your credentials.
• New installations use the REST API automatically and do not show the API Type setting.

Generate your REST API keys

↑ Back to top

Follow the USPS APIs Migration Onboarding Guide to create or sign in to a USPS Business Account, create an app, and retrieve its Consumer Key and Consumer Secret. USPS maintains the account and app screens shown in that guide. You can also start from the USPS Getting Started page.

Add your API credentials in WooCommerce

↑ Back to top

When you have the Consumer Key and Consumer Secret, go to WooCommerce > Settings > Shipping > USPS.

• Paste the Consumer Key into the REST API Key field.
• Paste the Consumer Secret into the REST API Secret field.
• Save the settings. The REST API Status should show Authenticated.

Legacy Web Tools connections

↑ Back to top

USPS retired Web Tools on January 25, 2026. Do not register for or configure a Web Tools account. If your plugin settings still show a legacy connection, update USPS Shipping Method and switch the API Type to REST.

Debug Mode

↑ Back to top

The debug mode in USPS can help you understand why rates are or aren’t returned, calculations appear incorrect, or certain services aren’t shown at checkout. Head to WooCommerce > Settings > Shipping > USPS to enable debug mode in USPS. Once enabled, when customers request USPS rates from the cart or checkout pages, log files will appear in WooCommerce > Status > Logs. Those will be in the file titled plugin-woocommerce-shipping-usps.

In these logs, you’ll see the request the site sent to USPS, the response WooCommerce receives back, and other additional information. Select the Additional context marker, the triangle icon, in the log file to expand it and see more details.

Set up and Configuration

↑ Back to top

1. Go to WooCommerce > Settings > Shipping > Shipping zones.
2. Edit the shipping zone where you want to offer USPS.
3. Click Add shipping method.
4. Select USPS, then click Continue.

• 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.
    5. Custom Flat Rate boxes – Enable this option to define adjusted dimensions for specific USPS Flat Rate boxes or envelopes. Use this when a package can close within its normal folds but needs more packing height than the predefined flat rate dimensions allow. See Custom Flat Rate boxes below.
  • API Rates – Check to enable non-flat rates using the USPS API. By default, all services are available, or you can 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 API (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 a more detailed explanation.

Available Shipping Services

↑ Back to top

These services are included with the USPS Shipping extension:

Domestic

↑ Back to top

• 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

International

↑ Back to top

• 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

Flat Rate Shipping Options

↑ Back to top

• 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) by applying USPS box dimensions. Packed boxes are then combined to offer a single rate (named by your ‘method title’).

Flat Rate Services

↑ Back to top

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

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

Custom Flat Rate Boxes

↑ Back to top

USPS Flat Rate services use USPS Flat Rate packaging. The USPS Shipping Method includes predefined package dimensions so the box packer can decide which Flat Rate boxes or envelopes fit the products in the cart.

In some cases, a product can fit inside a USPS Flat Rate envelope or box even if it is taller than the predefined package height. For example, a padded Flat Rate envelope may bulge while still closing within the normal folds allowed by USPS.

The USPS Shipping Method includes a Custom Flat Rate boxes setting. Use this setting to add custom Flat Rate box or envelope entries with adjusted dimensions and map each entry to a specific USPS Flat Rate package type. The box packer uses these entries when calculating which Flat Rate options are available.

Note: Only use custom Flat Rate dimensions for packages that still follow USPS Flat Rate packaging rules. USPS allows Flat Rate packaging to bulge if it can close within its normal folds, but the package cannot be enlarged or reconstructed.

To add a custom Flat Rate box or envelope:

1. Go to WooCommerce > Settings > Shipping > USPS.
2. Make sure Flat Rate Boxes and Envelopes is enabled.
3. Enable Custom Flat Rate boxes.
4. Click the Add custom Flat Rate box.
5. Enter the package details.
6. Save the settings.
7. Test the package with a cart that should use the custom Flat Rate entry. If needed, enable USPS debug mode and review the package selected by the box packer in WooCommerce > Status > Logs.

Name: This allows you to name the custom entry. The name appears in Debug mode output if the package is used.

L, W, H: These are the adjusted dimensions, in inches, that the box packer should use for this Flat Rate package.

Box weight: This is the weight of the empty package by itself. This weight is added to the total weight of the contents.

Max weight: This is the maximum weight the package can hold. This includes the weight of the package and the contents. Do not set this value to 0, as that will result in the custom Flat Rate box not being used.

Flat Rate packaging: This is the USPS Flat Rate package the custom entry should use, such as the Priority Mail Padded Flat Rate Envelope.

Example:

Field	Value
Name	Padded FRE (Bulging)
L	12.5
W	9.5
H	3.0
Box weight	0.05
Max weight	70
Flat Rate packaging	Priority Mail Padded Flat Rate Envelope

This example represents a padded Flat Rate envelope with adjusted height so the box packer can account for normal bulging. The returned rate is still the USPS Flat Rate service for the selected Flat Rate package type.

Parcel Packing Method

↑ Back to top

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

Per Item

↑ Back to top

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

Pack into boxes

↑ Back to top

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 quotes that are returned based on the customized box dimensions.

Weight based

↑ Back to top

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

Box Packing

↑ Back to top

When using the “Recommended” Parcel Packing Method, the plugin will use the built-in box packers to group items together into the package that is determined to be the ‘best fit’ and use the fewest number of packages. The box packers will use USPS Flat Rate packages (if enabled) and the custom packages that have been added to the Box Sizes table in the settings.

You have two box packing modes to choose from on the WooCommerce > Settings > Shipping > USPS page:

• The Speed Packer is the default option and is volume-based. This results in faster calculations and behavior that is easier to predict, but the math doesn’t always match real-world box packing. Once the Speed Packer has determined that an item can fit inside a package (by confirming that all product dimensions are less than or equal to the package dimensions), volume calculations are then used to determine how many other items can be packed into that same package based on the amount of remaining volume. For example, if a product has dimensions of 3×3×3, its volume is 27 (L x W x H = Volume). A box that has dimensions of 6×3×3 has a volume capacity of 54. That means the box can hold exactly two of that product, as the volume of the box is twice that of the product (27 × 2 = 54). If the order contains 3 (quantity) of that product, they cannot all be packed into a single 6×3×3 box. In that case, the Speed Packer will first look for a larger box that can hold all 3 items. If no such box exists, the 6×3×3 box will be packed to capacity with two items, and the remaining item will be packed into a second box.
• The Accurate Packer uses a more complex method that involves rotating each individual item multiple times during the packing process to find the ‘best fit.’ This approach more closely matches real-world box packing (compared to volume-based algorithms) but can take longer to complete and is not recommended if orders typically contain large quantities of products.

Important Note: Because of the complexity of box packing, there are some situations that will not be as accurate as a real person packing an order (see BIN Packing Problem) and some anomalies are to be expected with either box packer. However, adjustments to custom box settings can sometimes resolve these issues.

Setting up box sizes

↑ Back to top

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 mode output 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.

How the calculation works

↑ Back to top

The box packer:

1. Finds boxes that fit items being packed (uses H × W × 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.

Media Mail®

↑ Back to top

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:

Customer Usage

↑ Back to top

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

Troubleshooting

↑ Back to top

No rates returned, no rates available, “no shipping rates found”

↑ Back to top

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

All shipping rates are live from USPS, so there is likely something in the request or response that does not match USPS expectations.

• Shipping Zones may be set up incorrectly. Enable WooCommerce’s shipping debug mode to check if the address matches a shipping zone.
• Enable the USPS Shipping Method debug mode to check the USPS API response.
• 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 the USPS API. It uses wp_remote_post, which makes use of fsockopen/CURL.
• If API rates are enabled, make sure the origin postcode is included.

The returned rates are too high

↑ Back to top

• Check the Shipping Rates section – Commercial rates are cheaper.
• Check the selected parcel packing method. Packing individually usually results in higher costs.
• Check the Price Adjustment columns to see if the user is adjusting the returned price.
• If you are using Flat Rates, these values 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
• Enable Debug mode and check:
  • The request includes the right product dimensions
  • The rates being returned are the ones expected. For example, “First-Class Mail®” could be one of 10 different types of First-Class Mail®
  • How the debug response compares with the same request on the USPS price calculator .

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

↑ Back to top

In this case, you might be using a plugin such as the 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

↑ Back to top

USPS calls this service First-Class Mail International Flats. USPS permits it for eligible documents, not merchandise. USPS Shipping Method therefore does not return this rate when a package contains products with a declared value greater than zero. See the USPS international contents and customs requirements.

For eligible documents with no declared merchandise value, use the Recommended parcel packing method and make sure the package weight, dimensions, shape, and flexibility meet the current USPS First-Class Mail International standards.

Stamped Letter service not available

↑ Back to top

USPS determines eligibility from its current letter dimensions and shape requirements. Check the USPS domestic mail dimensions guide, then make sure the product and package dimensions in WooCommerce meet those requirements.

“API Authorization failure” or RateV4 errors

↑ Back to top

These messages refer to the retired Web Tools connection. Update USPS Shipping Method, switch the API Type to REST, and add your REST API key and secret. Do not request access to the legacy RateV4 or IntlRateV2 APIs.

“Your Web Tools API service has been disrupted” error

↑ Back to top

This message means the site is using the retired Web Tools connection. Do not try to restore the legacy connection. Update USPS Shipping Method and switch to REST.

“UserName exceeds maximum length of 12 characters” error

↑ Back to top

This message refers to the legacy Web Tools User ID. Switch to REST, which uses a Consumer Key and Consumer Secret instead.

Developer customization

↑ Back to top

To remove USPS Flat Rate envelopes while keeping Flat Rate boxes available, see Remove USPS Flat Rate envelopes with a code snippet.