Search
Documentation / Plugins / WooCommerce / Extensions

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.

Configuration ↑ Back to Top

  1. Once the plugin has been activated, go to WooCommerce > Settings > Shipping Methods.
  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 own user ID by signing up to USPS, if the USPS ID is blank it will default to an account ID that was registered by Woo. This is optional. If you use your own USPS ID, you need to call USPS and have them set it to ‘production’.
      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. Flat Rate Boxes - Enable this option to offer shipping using USPS Flat Rate boxes. See below for more details on this.
      2. Standard Services – Enable this option to offer shipping using the USPS API.
        1. Parcel Packing Method – See below.
        2. Offer Rates – Choose to return all rates (user will get the choice) or just return a single rate.
        3. Services – Here you can rename, and re-order, USPS shipping rates.
      3. Fallback – If not rates are returned from the API, optionally offer a fallback cost.
Please note: The UPS shipping extension is a calculator for all products in the cart, and does not exclude products based on shipping classes.

Flat Rate Boxes ↑ Back to Top

If enabled, the flat rate box option will create a single quote made up entirely of USPS Flat Rate Boxes. 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’).

Parcel Packing Method ↑ Back to Top

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

Per-Item

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.

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.

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.
Back to the top