VibeFox UPS for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later, with the cURL extension. The module refuses to install on older PHP versions or without cURL.

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 module 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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox UPS in the module list later and click Configure.

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

4. 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.

5. If your UPS account currency differs from your shop default currency, enter UPS account currency and Exchange rate.

6. Optionally enter fixed prices as a fallback and click Save.

On install the module creates the UPS carrier with the delivery time text UPS delivery. The carrier is assigned to all zones and all customer groups. You can change zones, customer groups, delivery time, logo and size limits in Shipping > Carriers. Do not set prices there: the price always comes from the module.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox UPS > Configure. They apply to every zone of the carrier. Each section has its own Save button, which saves the whole page. Every save clears the cached UPS token and rates. 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 carrier 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 shop weight or dimension unit is not known to the module. Numbers that are not valid, a wrong box size and a Min weight above Max weight are reported when you save, and the old value is kept.

General

Enable UPS shipping: turns the carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.

Name: the carrier name shown to the customer at checkout. Default: UPS. Required, 64 characters at most.

Tax status: the tax rule of the carrier, or None. UPS rates are quoted without taxes. With a tax rule the shop adds its shipping tax on top.

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. Shop 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 shop 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 your shop 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.

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 shop 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 carrier in that case)

Country prices: prices in your shop default currency, tax excluded, per destination country. Click Add country to add a row and the remove button to delete one. The country * 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 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 shop default currency when no country price matches. Leave it empty to hide the carrier in that case.

Fixed price is: Per order 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. If one product has no fixed price, the carrier is hidden. UPS live rates are always quoted for the whole cart weight.

Conditions

Free shipping from: the cart subtotal (products that need shipping, after discounts, before tax) from which this carrier is free. No request goes to UPS then. Leave it empty to never offer free shipping.

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

Min weight: the minimum cart weight in kg for this carrier to appear. 0 means no limit.

Max weight: the carrier is hidden above this cart weight in kg. Default: 70, the UPS limit per package (70 kg / 150 lbs). 0 means no limit, empty means 70. Min weight cannot be above Max weight.

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

Availability without shipping zones

Normally the carrier is offered in the zones it is assigned to in Shipping > Carriers.

Ignore shipping zones: offer the carrier for the countries below, whatever zone matches. On save the carrier is added to all zones, and also to zones created later. Switching it off removes those zones again.

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

Advanced

Debug log: logs API requests and rate calculation to logs/vfd_upsx_debug.log.php in the module folder. The file cannot be opened from the web. API errors are always logged, even when this option is off. Credentials, tokens and customer addresses are never logged.

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 module deletes the settings, the carrier, cached tokens and rates, the log and the UPS services saved with orders. The orders themselves are kept. When off, everything is kept for a re-install.

How it works at checkout

At the shipping step PrestaShop asks the module for the UPS price. Only physical products count: virtual products add no weight and are not included in the subtotal. The module first checks the conditions: the countries of Ignore shipping zones, cart weight and minimum subtotal. If free shipping applies, the price is 0 and no request goes to UPS.

The module 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. The price is calculated in your shop default currency and then shown in the customer's cart currency. UPS Access Point Economy is not quoted, because the module 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 carrier is hidden. The customer never sees UPS error texts.

If you edit the carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.

The module 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

When an order is placed with a live UPS rate, the UPS service is saved with the order. The back office order page shows a UPS block with the UPS service, for example UPS Ground, and the Live rate (excl. tax). Later changes to the cart in the back office do not change it. Orders with a fixed price or free shipping have no such block.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox UPS is the first block on Modules > Module Manager > VibeFox UPS > Configure, 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 shop. Below them are the line Product: presta-shipping-ups and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office 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 shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the UPS carrier is not shown to customers at checkout and no rate is calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carrier is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module 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. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group, or turn on Ignore shipping zones and check Countries. Check the weight limits and Minimum subtotal. Without working UPS credentials the carrier needs a fixed price (Country prices or Fallback cost). Products can also be limited to certain carriers in the product page.

Live rates do not appear: check the warnings at the top of the Configure page. Turn on Debug log, reload the checkout and look at the Log field on the module 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 shop 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.

The page warns that the shop weight or dimension unit is not known: weights are then read as kg and the box size as cm. Set a standard unit (kg, g, lb or oz; cm, mm, m or in) in International > Localization, section Local units.

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

The page says the UPS carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.

For developers: the hooks actionVfdUpsxAllowedServices and actionVfdUpsxExcludedServices restrict the UPS services that can be shown. actionVfdUpsxRateRequest changes the rate request, actionVfdUpsxApiBaseUrl the API address and actionVfdUpsxCurrencyCodes maps currency codes returned by UPS.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox UPS and choose Uninstall. The license key and the license status are always removed. The cached UPS token and rates are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history), and the settings, the log and the UPS services saved with orders are removed. If it is off, the carrier is only disabled and the settings are kept. Installing the module again, or a Reset, gives the carrier back the status it had before.

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