UPS Shipping Method

UPS is a premium shipping method which let you get shipping rates from the UPS 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 measurements in Inches (in) and weight in Pounds (lbs), but other units can be converted automatically.

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

Please note! This extension does not do freight shipping and there is a weight limit of 150 lbs. 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. To download your extension go to your Account Dashboard ‘Downloads’ tab here:
  2. Next, upload the plugin folder via FTP to the /wp-content/plugins/ directory.
  3. Activate the plugin through the ‘Plugins’ menu in WordPress.
  4. Go to your ‘My License’ tab in your WooThemes Account Dashboard here: and copy the license key number.
  5. Finally, go to: WordPress Dashboard > WooThemes Licenses menu option to enter your license key.

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 ‘UPS’.
  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. 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.
    4. API Settings - This section is where you input your API Details from UPS. Your API access details are obtained from the UPS website. After creating an account, you will need to Request an Access Key.
      1. UPS User ID – Get this from the UPS developer site when you signup.
      2. UPS Password – As set by you on sign up.
      3. UPS Access Key – This will be sent to you after sign up.
      4. UPS Shipper Number – This will be sent to you after sign up.
      5. Origin Postcode – This should be set to the postcode from which you will ship. It is sent to the UPS API.
      6. Origin Country – This should be set to the country from which you will ship. It is sent to the UPS API.
      7. Negotiated Rates – Whether to enable negotiated rates, you can read more about that here. This needs to be approved by UPS, or the API may return an error. It is sent to the UPS API.
      8. Debug Mode – Enable the debug mode. All API call requests and responses are output on the cart page for debugging.
    5. Pickup and Destination
      1. Pickup – Pickup method to be used (
      2. Residential – Whether to indicate that deliveries are to residential or commercial addresses.
    6. Services and Packaging
      1. Services – Here you can rename, and re-order, UPS shipping rates.
      2. Offer Rates – Here you can select whether to display all rates available, or only the cheapest.
      3. Fallback – Should no rate be found, you can enter a fallback amount which will be used for shipping costs.
      4. Parcel Packing Method – See below
      5. UPS Packaging – The packaging type from UPS to use.
Please note: The UPS shipping extension is a calculator for all products in the cart, and does not exclude products based on shipping classes.

Parcel Packing Methods ↑ Back to Top

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

Default: Pack Items Individually

Each item in your cart (non virtual) will be sent to the UPS API. Quotes for all items will be combined for the final cost. Only the weight is required for this, but we recommend also entering product dimensions for a more accurate quote. For even more accuracy we recommend the box packer method.

To use this method add a new product then scroll down to Product Data > Shipping to enter the product dimensions.

Recommended: Pack into boxes with weights and dimensions

Using this method you will create your own custom box sizes in the UPS Settings. The extension will use the product(s) weight/dimensions added to the cart, filling the custom box size smallest to larges based on volume and size, then send the number of boxes/size to the UPS API for the shipping estimate. We recommend using both product weight & dimensions for this option for the most accuracy.

Selecting this option you must follow the steps listed below for UPS Packaging or Custom Box Packing in order for this method to work.

UPS Packaging ↑ Back to Top

UPS offers standard boxes for shipping. If you would like to use the standard box sizes offered by UPS go to the WooCommerce > Settings > Shipping > UPS where it says UPS Packaging:


Start typing the package you wish to include and it will auto-populate in the field for you.

Please note: If you chose the Recommended: Pack into boxes with weights and dimensions option but have not chosen any UPS Packaging, nor defined any custom boxes (as explained below), the plugin will display the following error message: “UPS is enabled, and Parcel Packing Method is set to ‘Pack into boxes’, but no UPS Packaging is selected and there are no custom boxes defined. Items will be packed individually.”

Custom Box-Packing ↑ Back to Top

The box packer included with this shipping method will group items into boxes 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

Go to WooCommerce > Settings > Shipping > UPS > Custom Boxes and select Add Box to set up the boxes dimensions:

Box Settings

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.

Handling Fees ↑ Back to Top

To add handling fees to the shipping calculations you can use one of the Price Adjustment columns in the Services section.  Each UPS service can be increased separately using the price adjustment columns on the row.

Use the Price Adjustment ($)  column to add a flat amount to the shipping quote.  In this example the 3 Day Select and Ground shipping methods will be increased by $3.50.


Use the Price Adjustment (%) to increase the shipping quote by a percentage. In this example the 3 Day Select and Ground shipping methods will be increased by 1% of the quote returned from UPS.



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.

FAQ ↑ Back to Top

I dropship items. Can I use multiple origin zip codes?

No, the WC UPS plugin currently uses one origin zip code for requesting quotes from UPS.

Troubleshooting ↑ Back to Top

No rates returned/no rates available

  1. Ensure your API credentials are correct.
  2. Enable development mode, or turn on WP_DEBUG to see debugging information on the cart page. This will often reveal the problem.
  3. Check your products have sizes and weights set – without this the calculation cannot be performed.

Customize ↑ Back to Top

Please note: The following is considered custom code, and while we’re happy to give it to you here, we are unable to support you with or help you customize it to suit your store. Please only use it if you are comfortable with PHP and custom coding.

If you’d like to remove UPS as a shipping option for some shipping classes, you can add the following code to your functions.php. You will need to change the shipping classes used on the 14th line:

Please remove the at the beginning if you do not see a ?> before or you notice an error after adding the code.

Back to the top