VP USPS Shipping for VirtueMart User Guide

Details

Introduction

VP USPS Shipping for VirtueMart is a plugin that shows real-time shipping rates from the United States Postal Service (USPS) in your VirtueMart store. When a customer adds items to their cart and goes to checkout, the plugin contacts USPS to get the exact shipping cost based on the package weight, size, and destination.

This plugin uses the new USPS REST API (launched 2024-2025) which replaced the old USPS Web Tools XML API that was retired in January 2026. The new API uses modern OAuth 2.0 security and JSON data format.

Key Features

  • Real-time shipping rates from USPS
  • Supports all major USPS domestic services (Priority Mail, Priority Mail Express, Ground Advantage, Media Mail, Library Mail)
  • Supports international services (Priority Mail International, Priority Mail Express International, First-Class Package International)
  • Flat rate boxes and envelopes supported
  • Smart flat rate feature checks if products fit inside flat rate containers
  • Multi-box shipping for heavy orders
  • Handling fees (flat or percentage)
  • Shipping restrictions by country, ZIP code, order amount, and product category
  • Rate caching to minimize API calls
  • Works with Joomla 3, 4, and 5 (VirtueMart 3.8.x and 4)

Requirements

Before you install this plugin, make sure your website meets these requirements:

  • Joomla 3.x, 4.x, or 5.x
  • VirtueMart 3.8.x or 4.x
  • PHP 7.1 or higher (PHP 8.1+ recommended for Joomla 5)
  • cURL PHP extension enabled (most hosting providers have this by default)
  • A USPS Business Account with API access (free to create - see next section)

Getting Your USPS API Credentials

To use this plugin, you need API credentials from USPS. Follow these steps to get them:

Step 1: Create a USPS Account

  1. Go to https://developers.usps.com in your web browser.
  2. Click the "Sign Up" or "Get Started" button.
  3. If you already have a USPS.com business account, you can sign in with those credentials. If not, create a new account.
  4. Fill in your business details (name, email, address).
  5. Verify your email address by clicking the link USPS sends you.

Step 2: Register an Application

  1. After signing in, go to your Dashboard or Apps section.
  2. Click "Create App" or "Add Application".
  3. Give your application a name. For example: "My Store Shipping" or your store name.
  4. In the API products or permissions section, make sure you add:
    • Domestic Prices (for US shipping rates)
    • International Prices (for international shipping rates)
  5. Save your application.

Step 3: Get Your Credentials

  1. After creating your app, you will see your Consumer Key and Consumer Secret.
    • Consumer Key = This is your Client ID (you will enter this in the plugin settings)
    • Consumer Secret = This is your Client Secret (you will enter this in the plugin settings)
  2. Copy both values and keep them in a safe place. You will need them in the plugin configuration.

Note: You do not need a USPS EPS or commercial account number to show commercial rates. The plugin requests commercial base rates using only your Client ID and Client Secret. Just set Rate Type to Commercial in the plugin settings.

Important Notes About USPS API

  • There is no cost to create a USPS developer account or use the pricing APIs.
  • USPS has a rate limit of 60 requests per hour per API. The plugin includes caching to work within this limit, but very high-traffic stores should be aware of this.
  • You can test with the STAGING server before going live. The staging server uses the same credentials but connects to the USPS test environment.

Installing the Plugin

Method 1: Install from ZIP File

  1. Log in to your Joomla administrator panel.
  2. Go to System > Install > Extensions.
  3. Click the Upload Package File tab.
  4. Click "Or browse for file" and select the plugin ZIP file.
  5. Click Upload & Install.
  6. You should see a success message.

Method 2: Discover Install (if files are already on the server)

  1. Upload the vpusps folder to /plugins/vmshipment/ on your server.
  2. In Joomla admin, go to System > Install > Discover.
  3. Click "Discover" to find new extensions.
  4. Find "VP USPS Shipping for VirtueMart" in the list.
  5. Select it and click "Install".

Enable the Plugin

After installation, you must enable the plugin:

  1. Go to System > Manage > Plugins.
  2. Search for "USPS" in the search box.
  3. Find "VP USPS Shipping for VirtueMart" in the list.
  4. Click the red circle (disabled) icon to enable it, or click on the plugin name and set Status to Enabled.
  5. Click Save & Close.

Configuring the Plugin

After enabling the plugin, you need to configure your USPS API connection and general settings.

  1. Go to System > Manage > Plugins.
  2. Click on "VP USPS Shipping for VirtueMart" to open its settings.

Connection Settings

Setting Description
USPS Client ID Enter the Consumer Key you got from developers.usps.com. This is required.
USPS Client Secret Enter the Consumer Secret you got from developers.usps.com. This is required.
USPS Server Choose PRODUCTION for your live store. Use STAGING only for testing.
Proxy Server Only needed if your web hosting requires a proxy for outgoing connections. Most users can leave this empty.

General Settings

Setting Description
Rate Type Retail shows standard USPS prices (what a customer would pay at the post office). Commercial shows the lower commercial base prices. No USPS account number is required for either type - commercial base rates are available to all API users.
Machinable Packages Set to Yes if your packages can be processed by automated USPS machines. Most packages should be set to No. Machinable packages may get slightly lower rates. This setting applies to single-piece and Ground services (domestic and international). USPS Flat Rate Boxes and Envelopes are always quoted with their USPS-mandated classification, so this setting has no effect on flat rate services.
Pad Cart Weight Adds extra weight to account for packaging materials. Enter a percentage with the % sign. For example, 15% adds 15% to the product weight. Leave as 0% for no padding.
Smart Flat Rate When enabled, the plugin checks if your products physically fit inside flat rate boxes/envelopes. If they don't fit, that flat rate option won't show. See the Smart Flat Rate section for details.
Smart Flat Rate Fit Tolerance Optional slack, in inches, added to each interior dimension of a flat rate container before the Smart Flat Rate fit check. Leave at 0 in most cases. Use a small value like 0.05 if products whose dimensions exactly equal the container interior are being rejected. Has no effect when Smart Flat Rate is off.
Show Cheapest Option Only When several USPS methods qualify for the same cart, optionally hide the more expensive ones so the shopper sees only the lowest-priced option. Choose the comparison group: flat rate boxes only, all flat rate options (boxes and envelopes), or every enabled USPS service. Leave Off to show all qualifying methods. See Showing Only the Cheapest Option.
Maximum Box Weight The heaviest a single box can be in pounds. USPS allows up to 70 lbs per package.
Allow Multiple Boxes When enabled, if the total cart weight exceeds the maximum box weight, the plugin automatically splits products into multiple boxes and adds up the shipping costs.
Report USPS Errors When enabled, any error messages from USPS will be shown to the customer during checkout. Useful for testing but should be disabled on live stores.

Click Save & Close when done.

Setting Up Shipping Methods

After configuring the plugin, you need to create shipping methods in VirtueMart. Each shipping method represents one USPS service (for example, "Priority Mail" or "Ground Advantage").

Creating a Shipping Method

  1. In Joomla admin, go to VirtueMart > Shop > Shipping Methods.
  2. Click New to create a new shipping method.
  3. Fill in the fields:
Field What to Enter
Shipping Method Name The name shown to customers, e.g., "USPS Priority Mail"
Published Set to Yes
Description Optional description for customers
Shipment Method Select "VP USPS Shipping for VirtueMart" from the dropdown
  1. Click Save (not Save & Close, so you can configure the method details).
  2. A new Configuration tab will appear. Click on it.

Configuring Each Shipping Method

In the Configuration tab, set these options:

Setting Description
USPS Service Choose which USPS service this method represents (e.g., Priority Mail, Ground Advantage).
Outer Box Length / Width / Height Optional. The actual outer dimensions of the box you ship in for this method. When all three are filled in with positive numbers, the plugin sends these dimensions to USPS instead of the packed product dimensions. This is useful when your shipping box is larger than the product itself (for example, a 13x7x7 box for a small bottle). Applies to non-flat-rate services only (Priority Mail, Priority Mail Express, Ground Advantage, etc.). Leave blank to use the product dimensions.
Outer Box Unit of Measure The unit for the Outer Box dimensions above: Inches (IN) or Centimeters (CM). USPS expects inches, so CM values are converted automatically. Defaults to inches.
Logo Optional logo image to show next to the shipping option.
Tax Select a tax rule if you charge tax on shipping. The plugin always returns the shipping cost before tax; VirtueMart applies this rule and adds the shipping tax into the cart's overall tax total (it is not added onto the shipping option itself).
Apply Handling Fee Add an extra fee on top of the USPS rate. See Handling Fees.
Handling Fee Amount The fee amount (dollar value or percentage).

Under Restrictions, you can limit when this shipping method appears:

Setting Description
Countries Only show this method for specific countries. Leave empty for all countries.
ZIP Range Start/End Only show for ZIP codes in this range.
Min/Max Order Amount Only show when the cart total is within this range.
Categories Only show when products from these categories are in the cart.
Blocking Categories Hide this method when products from these categories are in the cart.
  1. Click Save & Close.

For a typical US store, we recommend creating these shipping methods:

  1. USPS Ground Advantage - Cheapest option, 2-5 business days
  2. USPS Priority Mail - 1-3 business days
  3. USPS Priority Mail Express - Overnight to 2 days

If you ship flat rate, add:

  1. Priority Mail Small Flat Rate Box
  2. Priority Mail Medium Flat Rate Box
  3. Priority Mail Flat Rate Envelope

For international shipping:

  1. Priority Mail International
  2. First-Class Package International (for small, lightweight items)

Available Shipping Services

Domestic Services (within the US)

Service Typical Delivery Best For
Priority Mail 1-3 business days Most shipments, good balance of speed and price
Priority Mail Express Overnight to 2 days Urgent deliveries
USPS Ground Advantage 2-5 business days Economy shipping, replaced First-Class Package and Retail Ground
First-Class Package Service 2-5 business days Small, lightweight items (under 13 oz). Retail rates are quoted by USPS as Ground Advantage.
Media Mail 2-8 business days Books, CDs, DVDs, and other media only
Library Mail 2-8 business days Materials sent to/from libraries and schools

Flat Rate Services (fixed price regardless of weight up to 70 lbs)

Service Container Size
Priority Mail Small Flat Rate Box 8.625" x 5.375" x 1.625"
Priority Mail Medium Flat Rate Box 11" x 8.5" x 5.5"
Priority Mail Large Flat Rate Box 12" x 11.75" x 5.5"
Priority Mail Flat Rate Envelope 12.5" x 9.5"
Priority Mail Legal Flat Rate Envelope 15" x 9.5"
Priority Mail Padded Flat Rate Envelope 12.5" x 9.5"

Similar flat rate options are available for Priority Mail Express.

International Services

Service Typical Delivery Best For
Global Express Guaranteed 1-3 business days Premium expedited international (fulfilled via FedEx). Requires a USPS account with GXG enabled — without it, USPS returns "no valid international price group".
Priority Mail Express International 3-5 business days Fastest standard international option
Priority Mail International 6-10 business days Standard international shipping
First-Class Package International Varies by country Small, lightweight items (up to 4 lbs)

International flat rate boxes and envelopes are also available.

Service Limits and Restrictions (Official USPS Documentation)

USPS limits change periodically (weight ceilings, country restrictions, prohibited items, dimensional surcharges). When you need the authoritative answer for a specific service, country, or item, consult the official USPS pages below — not third-party summaries.

Most useful single reference:

Page What it covers
Country Price Groups and Weight Limits Per-country maximum weight for every international service. The single best page when you see a "weight limit for the associated international price group" error — it tells you the exact cap for the destination country.

Service rules and packaging (Postal Explorer):

Manual What it covers
International Mail Manual (IMM) Complete rulebook for every international service — packaging, prohibited items, prep, customs forms.
Domestic Mail Manual (DMM) Domestic equivalent — physical standards (DMM §121), content restrictions, prep requirements.
Shipping Restrictions Prohibited/restricted items overview for domestic and international.

Per-service quick reference pages (usps.com):

Service Link
USPS Ground Advantage https://www.usps.com/ship/ground-advantage.htm
Priority Mail https://www.usps.com/ship/priority-mail.htm
Priority Mail Express https://www.usps.com/ship/priority-mail-express.htm
First-Class Package Service https://www.usps.com/ship/first-class-mail.htm
Media Mail / Library Mail https://www.usps.com/ship/mail-shipping-services.htm
Priority Mail International https://www.usps.com/international/priority-mail-international.htm
Priority Mail Express International https://www.usps.com/international/priority-mail-express-international.htm
First-Class Package International Service https://www.usps.com/international/first-class-package-international-service.htm
Global Express Guaranteed https://www.usps.com/international/global-express-guaranteed.htm

Tip — diagnosing "weight limit" or "no valid international price group" errors: open the Country Price Groups page, find your destination country, and check the per-service max weight. USPS limits vary widely by country (e.g. Priority Mail Express International is 70 lb to Canada but only ~44 lb to India). If your product exceeds the country's limit for one service, the cart will simply skip that method — try a different USPS service or carrier.

Smart Flat Rate Feature

When Smart Flat Rate is enabled in the plugin settings, the plugin uses a 3D box packing algorithm to check if your products will physically fit inside a flat rate container.

How It Works

  1. The plugin knows the exact interior dimensions of each USPS flat rate box and envelope.
  2. When a customer adds items to their cart, the plugin tries to "virtually pack" the products into the flat rate container.
  3. If all products fit, the flat rate option is shown.
  4. If the products don't fit, that flat rate option is hidden.

Setup Tips

  • Make sure all your products have accurate dimensions (length, width, height) set in VirtueMart.
  • Each flat rate method is checked independently, so every container the products fit in is offered. If you would rather show just one flat rate option, enable Show Cheapest Option Only (set it to Cheapest flat rate box only or Cheapest flat rate option) so the shopper sees only the least expensive box or envelope that fits. See Showing Only the Cheapest Option.
  • Products without dimensions will be treated as zero-size and will always "fit."
  • If products whose dimensions exactly match a container's interior are being rejected, set a small Smart Flat Rate Fit Tolerance (for example 0.05 inches) in the plugin's General Settings to add a little slack to the fit check.

Showing Only the Cheapest Option

If you enable several USPS methods that can all carry the same cart - for example Small, Medium and Large Flat Rate Box - a shopper would normally see all of them. The Show Cheapest Option Only setting (plugin General Settings) lets you collapse the choice to just the lowest-priced option instead.

Modes

Mode What shows
Off Every qualifying method is shown (default).
Cheapest flat rate box only Among the flat rate boxes that fit, only the cheapest is shown. Flat rate envelopes and weight-based services (Priority Mail, Ground Advantage, etc.) are unaffected and still show.
Cheapest flat rate option (boxes and envelopes) Among all flat rate boxes and envelopes that fit, only the single cheapest flat rate option is shown.
Cheapest of all enabled USPS services Only the single cheapest of every qualifying method is shown.

Notes

  • The comparison uses the price the shopper sees, including any handling fee.
  • Prices are compared after fitting and restriction checks, so only methods that actually apply to the cart compete.
  • This pairs well with Smart Flat Rate: enable Smart Flat Rate so only boxes the products fit in qualify, then use Cheapest flat rate box only so the shopper is offered the least expensive box that works.
  • If the cart contents change so a different option becomes cheapest, the previously selected (now dearer) option is dropped and the new cheapest is offered.

Multi-Box Shipping

When Allow Multiple Boxes is enabled:

  1. If the total cart weight exceeds the maximum box weight (default 70 lbs), the plugin splits products into multiple boxes.
  2. The USPS rate is calculated for each box separately.
  3. The total shipping cost is the sum of all box rates.

The plugin packs products into each box by both weight and size, so the exact split depends on the individual product weights and dimensions. Boxes are not always filled to a neat round number.

Note: If you set a Pad Cart Weight percentage, the effective per-box weight cap is lowered by that percentage so the padded weight still stays under your maximum. For example, with a 70 lb maximum and 15% padding, each box is packed to about 59.5 lbs of products and ships at roughly 68 lbs once the padding is added back.

Example

For a customer ordering 100 lbs of products with the max box weight at 70 lbs and no padding, a typical split is:

  • Box 1: about 70 lbs
  • Box 2: about 30 lbs
  • Total shipping = Rate for Box 1 + Rate for Box 2

Handling Fees

You can add a handling fee on top of the USPS shipping rate for each shipping method:

Fee Type How It Works Example
No Handling Fee No extra charge -
Flat Dollar Fee Fixed dollar amount added Enter 2.50 to add $2.50
Percentage of Shipping Cost Percentage added to the USPS rate Enter 10% to add 10% of the shipping cost
Percentage of Total Cart Percentage of the cart subtotal Enter 5% to add 5% of the cart total

The handling fee is added to the USPS rate and the combined amount is rounded to your store currency's normal number of decimal places (cents), so the price shown at checkout, the price charged, and the saved order record all match to the penny. For example, a $31.50 rate with a 5% fee becomes $31.50 + $1.575 = $33.075, which is shown and charged as $33.08. This amount is before tax - any shipping tax appears in the cart's tax line, not on the shipping option itself.

Shipping Restrictions

Each shipping method can be restricted to show only under certain conditions:

Country Restrictions

  • Select one or more countries from the list.
  • The shipping method will only appear when the customer's shipping address is in one of those countries.
  • Leave empty to allow all countries.

ZIP Code Range

  • Enter a start and end ZIP code.
  • The shipping method will only appear for ZIP codes in that range.
  • Useful for limiting delivery areas.

Order Amount Range

  • Set a minimum and/or maximum order amount.
  • For example, you could offer free Priority Mail Express only for orders over $100.

Category Restrictions

  • Categories: The method is only available when a product from the selected categories is in the cart.
  • Blocking Categories: The method is hidden when a product from the selected categories is in the cart. Useful for oversized or hazardous items that can't ship via certain methods.

Troubleshooting

No shipping rates appear at checkout

  1. Check your credentials: Go to the plugin settings and verify your Client ID and Client Secret are correct.
  2. Enable error reporting: Temporarily set "Report USPS Errors" to Yes in the plugin settings. Then try checkout again to see if USPS returns an error message.
  3. Check product weights: USPS requires a weight greater than zero. Make sure all your products have weights set in VirtueMart.
  4. Check the store address: Go to VirtueMart > Shop > Shop and make sure the store's billing ZIP code is filled in. USPS needs this as the shipping origin.
  5. Check the server setting: Make sure the USPS Server is set to PRODUCTION (not STAGING) on your live site.

"Failed to connect to USPS" error

  • Your Client ID or Client Secret is wrong. Double-check them at developers.usps.com.
  • Your server might not be able to connect to the USPS API. Check if your hosting blocks outgoing HTTPS connections.
  • If your hosting requires a proxy, enter the proxy URL in the plugin settings.

"USPS shipping rates are temporarily unavailable" message

  • This means the plugin hit the USPS rate limit (60 requests per hour). Wait a few minutes and try again.
  • The plugin caches rates to avoid this, but very high traffic or frequent cart changes can exceed the limit.

Shipping rates seem too high or too low

  • Check if the Rate Type is set correctly (Retail vs Commercial). USPS retail prices are higher than commercial prices - for example, the Large Flat Rate Box costs more at retail than commercial. If you want the lower rates, set Rate Type to Commercial (no account number needed). The rate USPS returns is the true published price for that service, so a retail rate that looks high is usually correct - compare it against the matching retail price on usps.com.
  • Check if Pad Cart Weight is adding extra weight.
  • Verify product weights are in the correct unit (pounds, not kilograms if you set the weight to pounds).

Flat rate options not showing

  • If Smart Flat Rate is enabled, the products might not fit in the flat rate container. Check your product dimensions.
  • Make sure the product dimensions are set in the correct unit.

Rate request returns HTTP 400 from USPS

If administrator/logs/vpusps_log.php shows a 400 response from either /prices/v3/base-rates/search (domestic) or /international-prices/v3/base-rates/search (international), the most common causes are:

  • "Pricing failure. Mail piece was over the weight limit for the associated international price group." USPS enforces a per-country weight cap for each service that's often lower than the service's global maximum. For example, Priority Mail Express International is 70 lb to Canada but only ~44 lb to India. Look up the destination country in the Country Price Groups and Weight Limits page and confirm your product weight is within the per-service cap.
  • Country mismatch. The shipping method's Countries restriction does not include the customer's destination country. Open the shipping method and add the destination country (or leave the field empty to allow all).
  • Postal code missing or wrong format. The destination postal code must match what USPS expects for that country (e.g. Canadian postal codes have the form A1A 1A1, UK postcodes vary).
  • mailClass mismatch. USPS occasionally renames mailClass identifiers (for example, what's marketed as "Ground Advantage" is USPS_GROUND_ADVANTAGE in the API, not GROUND_ADVANTAGE). The error response body lists the currently-accepted enum — open the log and read it. Domestic accepted values include USPS_GROUND_ADVANTAGE, PRIORITY_MAIL, PRIORITY_MAIL_EXPRESS, FIRST-CLASS_PACKAGE_SERVICE, MEDIA_MAIL, LIBRARY_MAIL, USPS_RETAIL_GROUND, PARCEL_SELECT, BOUND_PRINTED_MATTER, USPS_CONNECT_*. International accepted values: PRIORITY_MAIL_EXPRESS_INTERNATIONAL, PRIORITY_MAIL_INTERNATIONAL, FIRST-CLASS_PACKAGE_INTERNATIONAL_SERVICE, GLOBAL_EXPRESS_GUARANTEED.
  • rateIndicator mismatch. USPS keeps two separate enums for the rateIndicator field, one for the domestic endpoint and a narrower one for the international endpoint. International accepted values: E4, E6, E7, FA, FB, FE, FP, FS, PA, PL, SP, EP, HA, HB, HE, HL, HP, HS, LE. Domestic accepted values: 3D, 3N, 3R, 5D, BA, BB, BM, C1, C2, C3, C4, C5, CP, CM, DC, DE, DF, DN, DR, E4, E6, E7, FA, FB, FE, FP, FS, LC, LF, LL, LO, LS, NP, O1, O2, O3, O4, O5, O6, O7, OS, P5, P6, P7, P8, P9, Q0, Q6, Q7, Q8, Q9, PA, PL, PM, PR, SB, SN, SP, SR. USPS revises these enums occasionally; the plugin's current mirror lives in VpuspsRequestBuilder::DOMESTIC_RATE_INDICATOR_ENUM and VpuspsRequestBuilder::INTERNATIONAL_RATE_INDICATOR_ENUM. If you added a custom service code, verify its rateIndicator is in the matching list.

Debugging

To see detailed logs of what the plugin is doing:

  1. Enable Joomla's System Debug in System > Global Configuration > System > Debug System = Yes.
  2. The plugin writes logs to administrator/logs/vpusps_log.php.
  3. Check this file to see the API requests, responses, and any errors.
  4. Remember to turn off debug mode on your live site when done.

Frequently Asked Questions

Q: Does this plugin work with the old USPS Web Tools API?

No. The old USPS Web Tools API was retired in January 2026. This plugin uses the new USPS REST API at apis.usps.com which is the only way to get USPS rates going forward.

Q: Is there a cost to use the USPS API?

No. USPS provides the pricing APIs for free. You only pay the actual postage when you ship packages.

Q: Can I show both retail and commercial rates?

Not at the same time. The rate type is a plugin-level setting that applies to all shipping methods. Choose either Retail or Commercial.

Q: Do I need a USPS business account?

Yes. You need a USPS account to access the developer portal and get your API credentials. Business accounts are free to create. You do not need a separate commercial/EPS payment account or any paid plan to show commercial rates - the plugin requests commercial base rates, which USPS returns to all API users. (The old Web Tools API exposed these as "Commercial/Online" rates; the new REST API simply calls them commercial.)

Q: Does this plugin create shipping labels?

No. This plugin only gets shipping rates for display during checkout. To create shipping labels, you would use USPS.com, a shipping platform like Pirate Ship, or a separate label-printing extension.

Q: What happens if the USPS API is down?

If the USPS API is unreachable or returns an error, the shipping method will not appear during checkout. Customers can still complete their order using other available shipping methods.

Q: Can I use this plugin with multiple VirtueMart vendors?

Yes. The plugin gets the shipping origin address from each vendor's store settings in VirtueMart.

Q: What currency are the rates returned in?

USPS returns rates in US Dollars (USD). The plugin does not perform currency conversion. If your store uses a different currency, you may need a currency conversion solution.

Q: How does the rate limiting work?

USPS allows 60 API requests per hour. The plugin uses three levels of caching to stay within this limit:

  1. Page-level cache: Rates are stored during a single page load so they're not fetched twice.
  2. Session cache: Rates are remembered for the customer's session. They're only re-fetched when the cart weight, origin ZIP, or destination ZIP changes.
  3. Application cache: Rates are shared across all customer sessions for 60 minutes. If another customer ships to the same area with a similar cart, cached rates are used.

For most stores, this means the plugin makes far fewer than 60 API calls per hour.