VibeFox UPS for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

UPS Developer Portal app (for live rates only): log in to the UPS Developer Portal (developer.ups.com), create an app with the "Rating" product, link your UPS account and copy the Client ID and Client Secret. The plugin uses OAuth 2.0. No Access Key, user name or password is needed. For negotiated rates you also need your 6-character UPS account number. Without credentials, only the fixed prices are used.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_ups folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox UPS, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter the Client ID and Client Secret, your UPS account number (for negotiated rates) and the Ship from address: the postal code and, for the US and Canada, the 2-letter state.

6. If your UPS account currency differs from the store currency, enter UPS account currency and Exchange rate.

7. Add VibeFox UPS to a shipping zone in WooCommerce > Settings > Shipping > Shipping zones, or turn on Ignore shipping zones and choose countries.

8. Optionally enter fixed prices as a fallback.

Configuration

All settings are on one page: WooCommerce > Settings > Shipping > VibeFox UPS. They apply to every shipping zone. When you add the method to a zone, the zone window has only one field:

Title (zone): the name of this option at checkout. Leave it empty to use the global Name.

Every time you save the settings, the cached UPS token and rates are cleared. You can also click Clear cached UPS token and rates in the UPS API section. Warnings above the settings tell you when only one of Client ID and Client Secret is set, there are no credentials and no fixed prices, the ship-from postal code or state is missing, account rates are chosen without an account number, or the exchange rate is missing.

General

Enable/Disable: turns the method on or off in all zones at once.

Name: the shipping method name shown at checkout. Default: UPS.

Tax status: Taxable lets WooCommerce add its shipping tax on top, None does not. UPS rates are quoted without taxes, so tax is not charged twice.

UPS API (live rates)

Test mode: use the UPS test environment. Test rates are not real prices. Switch it off for live rates. Default: off.

Client ID: the Client ID of your app in the UPS Developer Portal.

Client Secret: the Client Secret of the same app.

UPS account number: your 6-character UPS shipper number, for example A1B2C3. Needed for account (negotiated) rates, optional for published rates.

Rates: which UPS prices are used.

Measurement units: the units sent to UPS. Store weights and sizes are converted.

Residential delivery: quote customer addresses as residential, with the UPS residential surcharge. Switch it off if you ship mostly to businesses. Default: on.

Box size: optional box dimensions in your store dimension unit, for example 30x20x15. UPS then applies dimensional weight. Leave it empty to quote by weight only.

UPS account currency: UPS quotes in the currency of the shipper account country, for example USD for the US, CAD for Canada or EUR for the euro area. Default: USD.

Exchange rate: only needed when the UPS account currency differs from the store currency. Enter the price of 1 unit of the account currency in your store currency, for example 0.92. Without it, such rates are not used and the fixed prices apply. Exchange rates are not updated automatically.

Ship from (the address UPS picks up from or where you drop off the parcels; used for live rates)

Country: the country you ship from. By default it is your store country.

State / province code: the 2-letter code, required for the US and Canada, for example NY, CA or ON.

City: the city you ship from.

ZIP / postal code: the postal code you ship from. UPS needs it to quote rates.

Fixed prices (used when no API credentials are entered and as a fallback when UPS returns no rate; leave both empty to hide the method in that case)

Country prices: prices in your store currency per destination country. Click + Add country to add a row and the cross to remove one. The row * Default applies to any other country. A weight column (XS up to 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL over 5 kg) overrides Price for that cart weight. Empty cells fall back to Price. 0 means free shipping. Rows without any price are removed when you save, and values that are not numbers are rejected with a message.

Fallback cost: a flat price in your store currency when no country price matches. Leave it empty to hide the method in that case.

Fixed price is: Per order charges the price once. Per item (each item priced by its own weight x quantity) prices every item by its own weight (the default weight when it has none) and multiplies it by its quantity. UPS live rates are always quoted for the whole cart weight.

Conditions

Free shipping from: the cart subtotal from which this method is free. The customer sees the method name with "(Free)" and no request goes to UPS. Leave it empty to never offer free shipping.

Minimum subtotal: show the method only when the cart subtotal is at least this amount. Leave it empty to always show it.

Min weight (kg): the minimum cart weight for this method to appear. 0 means no limit.

Max weight (kg): the method is hidden above this cart weight. Default: 70, the UPS limit per package (70 kg / 150 lbs). 0 means no limit.

Default product weight (kg): the weight used for products without a weight, in UPS rates, weight columns and the weight limits. Default: 0.5.

Excluded shipping classes: hide the method if the cart contains a product from any of these WooCommerce shipping classes.

Availability without shipping zones

Ignore shipping zones: offer the method for the countries below even without adding it to a shipping zone.

Countries: the destination countries for that mode. Leave empty to use all shipping countries of the store. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: logs API requests and rate calculation to WooCommerce > Status > Logs, source vfd-ups. API errors are always logged, even when this option is off. Credentials, tokens and customer addresses are never logged.

Remove data on uninstall: when on, deleting the plugin removes all plugin settings and zone methods. Deactivating never deletes settings.

How it works at checkout

When the customer enters a delivery address, WooCommerce asks the plugin for a rate. The plugin first checks the conditions: cart weight, minimum subtotal and excluded shipping classes. If free shipping applies, the method is shown as free and no request goes to UPS.

The plugin gets an OAuth token from UPS and keeps it until it expires. A token that UPS rejects is renewed automatically. It then asks the UPS Rating API for all services from your ship-from address to the customer's address, for the cart as one package. For countries with postcodes, the request waits until the customer has entered one. For shipments from the US to Canada or Puerto Rico the goods value is sent, as UPS requires.

The customer sees one option with the cheapest UPS service, converted to your store currency. UPS Access Point Economy is not quoted, because the plugin does not collect an Access Point address.

Each quote is cached for 1 hour. A failed request is remembered for 10 minutes, and a failed token request for 5 minutes, so an outage does not slow down every checkout update. The HTTP timeout is 15 seconds. Deactivating the plugin clears the cached token and rates.

If UPS gives no rate (API down, wrong credentials, no service), the price comes from Country prices, then from Fallback cost. If neither applies, the method is hidden. The customer never sees UPS error texts.

The method works on the classic checkout and on the Cart and Checkout blocks. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin calculates rates only. It does not offer UPS Access Point selection, create shipping labels or UPS shipments, book pickups or track parcels. It shows one option, not several UPS services. There is no box packing: the cart is quoted as one package. Exchange rates are not automatic.

Orders

For a live rate, the shipping line of the order stores the UPS service, for example UPS Ground. The shop manager sees it on the admin order screen.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox UPS. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, UPS is not shown to customers at checkout. Logged-in store managers still see it, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

UPS does not appear at checkout: check that the license is active, Enable/Disable is on, and the method is added to the zone of the customer's country (or Ignore shipping zones is on and the country is allowed). Check the weight limits, Minimum subtotal and Excluded shipping classes. Without working UPS credentials the method needs a fixed price (Country prices or Fallback cost).

Live rates do not appear: check the warnings at the top of the settings page. Turn on Debug log and open WooCommerce > Status > Logs, source vfd-ups. It shows OAuth errors (check the Client ID, Client Secret and Test mode), UPS error messages and currency problems.

The rate is in USD but the store is not: UPS returns rates in the currency of the shipper account. Set UPS account currency and Exchange rate. Without an exchange rate such rates are ignored and the fixed price is used.

"This measurement system is not valid for the selected country": leave Measurement units on Automatic, or pick the units UPS expects for your ship-from country.

Rates look outdated after a change: save the settings page or click Clear cached UPS token and rates.

For developers: the filters vfd_upsx_allowed_services and vfd_upsx_excluded_services restrict the UPS services that can be shown. vfd_upsx_rate_request changes the rate request, vfd_upsx_api_base_url the API address and vfd_upsx_currency_codes maps currency codes returned by UPS.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps the settings and only clears the cached token and rates. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin and the cached token and rates are always removed. Settings and zone methods are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their shipping lines.

UPS is a trademark of its respective owner. This plugin is not affiliated with or endorsed by UPS.