VibeFox UPS for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later, with the cURL extension.

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 extension 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

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package vfd_ups-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_ups.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_ups-oc3-(version).ocmod.zip. The extension adds no OCMOD modifications, so you do not need to refresh Extensions > Modifications. Instead of the Installer, you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox UPS and click Install (the green + button).

3. Click Edit (the pencil button) to open the settings page.

4. Paste your VibeFox license key into License key in the license block at the top of the Edit page and click Activate (see License key).

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 your store default currency, enter UPS account currency and Exchange rate.

7. Optionally enter fixed prices as a fallback, turn on Enable UPS shipping and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_ups.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox UPS, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 4 to 7 for OpenCart 3. The settings page and its fields are the same in both versions.

After install the method is off until you turn on Enable UPS shipping and save. The Ship from country starts as your store country. If you install the extension again after an uninstall, the UPS settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox UPS > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Every save clears the cached UPS token and rates. Only admin users with the modify permission for this extension can save the settings, clear the cache or clear the log.

If the name, the tax class, the sort order or the geo zone is not valid, nothing is saved and the page shows the reason, for example Enter a valid name (64 characters max, without < > ; = # { }). Nothing was saved. Numbers that are not valid (for example negative), a wrong box size, a Min weight (kg) above Max weight (kg) and price cells that are not numbers are reported when you save: that field keeps its old value and the rest is saved. 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 method is then never shown), the ship-from postal code or state is missing, account rates are chosen without an account number, the exchange rate is missing, or the store weight or length unit is not known to the extension.

General

The settings apply to every geo zone. UPS is offered as one shipping option at checkout.

Enable UPS shipping: shows or hides UPS at checkout. Default: off.

Name: the shipping method name shown to the customer at checkout. Default: UPS. Required, at most 64 characters, without < > ; = # { }.

Tax class: the tax class of the shipping cost, or None (default). UPS rates are quoted without taxes. With a tax class OpenCart adds its shipping tax on top.

Sort order: the position of UPS among the shipping methods at checkout. A whole number.

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. Clearing it also removes the saved Client Secret.

Client Secret: the Client Secret of the same app. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

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 (L x W x H): optional box dimensions in the length unit of your store (shown in the field name), 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 your store default currency. Enter the price of 1 unit of the account currency in your default currency, for example 0.92. Without it, such rates are not used and the fixed prices apply. Exchange rates are not updated automatically.

Cache: UPS tokens are cached until they expire (at most the OpenCart cache lifetime), rates for 1 hour, failed requests for 5 to 10 minutes. Click Clear cached UPS token and rates to empty the cache at once.

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. It is sent to UPS only for these two countries.

City: the city you ship from.

ZIP / postal code: the postal code you ship from. UPS needs it to quote rates. OpenCart has no store postcode, so enter it here.

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 default currency, tax excluded, per destination country. Click Add country to add a row and the remove button to delete one. * Default (all other countries) 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. A country row with no value for the weight passes on to the * row. Rows without any price are not saved.

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

Fixed price is: Per order (default) charges the price once, for the weight of the whole cart. Per item (each item priced by its own weight x quantity) prices every product 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 (products that need shipping, after the coupon, before tax) from which this method is free. No request goes to UPS then. 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 (default).

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, empty means 70.

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

Geo zone: offer UPS only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones. Not used with Ignore shipping zones.

Availability without shipping zones

Ignore shipping zones: do not check the geo zone. The method is offered for the countries below.

Countries: the destination countries for that mode. Leave it empty to use all enabled 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 storage/logs/vfd_upsx_debug.log.php (on OpenCart 4 system/storage/logs/vfd_upsx_debug.log.php). The file cannot be read from the web. API errors are always logged, even when this option is off. Credentials, tokens and customer addresses are never logged. When the file reaches 5 MB, it is moved to vfd_upsx_debug.old.log.php and a new log is started.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when on, uninstalling the extension deletes the UPS settings, cached tokens and rates and the log. The UPS services saved with orders are always kept. When off, everything is kept for a re-install.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The Client Secret is not exported.

Import: paste previously exported JSON and click Import to restore the settings, for example on another store. The values are checked like a normal save. The saved Client Secret is kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the UPS price. If a Geo zone is set and the address is outside it, UPS is not offered (with Ignore shipping zones the country list decides instead). Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the subtotal. The subtotal is the price of these products after the coupon discount and before tax. Gift certificates, reward points and store credit are not taken into account. The extension then checks the conditions: cart weight and minimum subtotal. If free shipping applies, the price is 0 and no request goes to UPS.

The extension gets an OAuth token from UPS and keeps it until it expires. A token that UPS rejects is renewed automatically and the request is repeated once. 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 where OpenCart requires a postcode, 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. The price is calculated in your store default currency, rounded to its decimals, and shown in the customer's currency with the tax of the selected Tax class. UPS Access Point Economy is not quoted, because the extension 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.

If UPS gives no rate (API down, wrong credentials, no service, another currency without an exchange rate), 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 reason is written to the debug log.

The extension 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.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks UPS in the window Shipping method options. The method works the same way as on OpenCart 3.

Orders

When an order is placed with a live UPS rate, the UPS service is saved with the order. The order page in Sales > Orders shows a UPS panel with the UPS service, for example UPS Ground, and the Live rate (excl. tax). These values are saved when the order is placed. Orders with a fixed price or free shipping have no such panel.

OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again. The saved UPS service is updated with it. If the customer changes to another shipping method, or the price becomes a fixed price or free shipping, the saved service is removed from the order. On OpenCart 4 the UPS panel is shown above the History section.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox UPS is the first block on Extensions > Extensions > Shipping > VibeFox UPS > Edit, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: opencart-shipping-ups and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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 and no rate is calculated. An admin user who is logged in to the admin in the same browser still sees the method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension always removes the license key and license status.

Troubleshooting

UPS does not appear at checkout: check that the license is active and Enable UPS shipping is on. Check Geo zone, or turn on Ignore shipping zones and check Countries. Check the weight limits and Minimum subtotal. Without working UPS credentials the method needs a fixed price (Country prices or Fallback cost). Check that the products have Requires Shipping set to Yes.

Live rates do not appear: check the warnings at the top of the Edit page. Turn on Debug log, reload the checkout and look at the Log field on the extension page. 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 (by ship-from country), or pick the units UPS expects for your ship-from country.

The page warns about the weight or length unit: without a weight class with the unit kg, unknown weight units are read as kg. Add a kg weight class in System > Localisation > Weight Classes. An unknown store length unit means Box size is read as cm. Use cm, mm, m or in as the length class of the store (System > Settings, tab Option).

Rates look outdated after a change: click Save on the extension page or Clear cached UPS token and rates.

The page says "Warning: You do not have permission to modify VibeFox UPS!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_ups (OpenCart 3) or extension/vfd_ups/shipping/vfd_ups (OpenCart 4) in System > Users > User Groups.

For developers: the extension triggers OpenCart events that other extensions can listen to: vfd_ups/allowed_services and vfd_ups/excluded_services restrict the UPS services that can be shown, vfd_ups/rate_request changes the rate request, vfd_ups/api_base_url the API address and vfd_ups/currency_codes maps currency codes returned by UPS.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox UPS. The license key and license status of this extension are always removed. OpenCart always resets Enable UPS shipping, Sort order, Tax class and Geo zone. The cached UPS token and rates are always removed. If Remove data on uninstall is on, the UPS settings and the debug log are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. The UPS services saved with orders are never removed, and existing orders keep their shipping method and cost.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox UPS in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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