VibeFox UPS for Adobe Commerce — Допомога

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL extension. Without cURL no request reaches UPS and only the fixed prices are used.

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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-ups-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/UpsShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_UpsShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox UPS. Paste your VibeFox license key into License key in the license block, the first row of the group, 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. If the UPS account currency differs from the base currency of your store, enter UPS account currency and Exchange rate. Optionally enter fixed prices as a fallback. Set Enable to Yes and click Save Config.

The module adds the UPS shipping method to Magento. Customers see it as UPS - Delivery (method title and method name). It is off after installation (Enable = No).

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox UPS, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Method title and Method name also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page and clears the cached UPS token and rates. Amounts accept "9.99" and "9,99".

If Method title or Method name is empty, longer than 64 bytes or contains one of the characters < > ; = # { }, or Sort order is not a whole number, Magento shows an error and nothing on the page is saved. Other wrong values do not stop the save: a number field that does not hold a number of 0 or more and a wrong Box size (cm) keep their previous value, a Min weight (kg) above Max weight (kg) keeps both previous weights, and invalid cells of Country prices are cleared. A warning names each such field.

While Enable is Yes, warnings after saving 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 hidden at checkout), and, with credentials, when the ship-from postal code is missing, the ship-from state is missing for the US or Canada, account rates are chosen without an account number, or the UPS account currency differs from the base currency without an exchange rate. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

Enable: shows or hides UPS at checkout. Default: No.

Method title: the carrier name shown in the cart and at checkout. Default: UPS. Required, at most 64 bytes.

Method name: shown after the method title, as "Method title - Method name". Default: Delivery. Required, at most 64 bytes.

UPS API (needed for live rates only)

Test mode (CIE): use the UPS test environment (CIE). Test rates are not real prices. Set it to No for live rates. Default: No.

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

Client Secret: the Client Secret of the same app. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved secret, type a new value to change it. To delete the saved secret, clear the field and click Save Config. Clearing Client ID also removes the saved secret. The secret is never shown in the page or written to the log.

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

Rates: which UPS prices are used.

Measurement units: the units sent to UPS. Product weights are converted.

Residential delivery: quote customer addresses as residential, with the UPS residential surcharge. Set it to No if you ship mostly to businesses. Default: Yes.

Box size (cm): optional box dimensions in centimetres for the whole package, for example 30x20x15. UPS then applies dimensional weight. Leave it empty to quote by weight only. Product dimensions are not used: Magento products have no standard dimensions.

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 base currency of your store. Enter the price of 1 unit of the account currency in your base currency, for example 0.92. 0 or empty turns the conversion off: such rates are not used and the fixed prices apply. Exchange rates are not updated automatically.

Cached UPS token and rates: click Clear cached UPS token and rates to drop the saved UPS token and quotes at once, without saving the page.

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. Leave it empty to use the shipping origin country of your store (Stores > Configuration > Sales > Shipping Settings > Origin).

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.

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 the base currency of your store, tax excluded, per destination country. Click Add country to add a row and Delete to remove one. The country * All other countries applies to any other country. A weight column (XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg, XL over 5 kg) overrides Price for that cart weight. Empty cells fall back to Price. 0 means free shipping. Empty rows are removed when you save. If a country has several rows, the first one is used.

Fallback cost: a flat price in the base 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, 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 method 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, in the base currency) from which UPS 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 the 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). Empty restores 70 kg, 0 removes the limit.

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

Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs).

Advanced

Ship to Applicable Countries: All Allowed Countries offers UPS for every country your store allows, Specific Countries only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries.

Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.

Debug log: writes API requests and rate calculations to var/log/vfd_upsx_debug.log.php in the Magento folder. The file cannot be opened from the web. API errors are always logged, even when this is off. Credentials, tokens and the customer's city and postal code are never logged.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the UPS settings and the log (see Uninstall). The license key and the cached UPS token and rates are always removed. Orders and the UPS services saved with them are never deleted.

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

The module has no tax field: if your store charges tax on shipping, set it in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping. UPS rates are quoted without taxes.

How it works at checkout

At the shipping step Magento asks the module for the UPS price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module first checks the countries, the cart weight and Minimum subtotal. If free shipping applies, the price is 0 and no request goes to UPS. A Magento cart price rule with free shipping also makes the price 0, without a request to UPS; the countries, weight limits and minimum subtotal still apply.

The module gets an OAuth token from UPS and keeps it until shortly before it expires. A token that UPS rejects is renewed once 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. The weight is rounded up to 0.1 and the box size up to whole units. For countries where Magento requires a postal code, 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 the base currency of your store; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it. 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. The cache is stored encrypted in the database and cleaned up by the Magento cron.

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

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. On the admin order page (Sales > Orders > View, Information tab) the UPS block shows UPS service: with the service name and code, for example UPS Ground (03), and Live rate (excl. tax): with the amount and the base currency. Later changes do not overwrite it. The block also works for older orders and when the module is switched off. Orders with a fixed price or free shipping have no such block. Customers do not see it.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox UPS is the first row of the VibeFox UPS group in Stores > Configuration > Sales > Delivery Methods, 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: magento-shipping-ups and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Delivery Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the UPS method is not shown to customers at checkout and no rate is calculated. The Magento storefront does not know that you are logged in to the Admin, so the method 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

UPS does not appear at checkout: check that the license is active and Enable is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum subtotal. Without working UPS credentials the method needs a fixed price (Country prices or Fallback cost).

Live rates do not appear: check the warnings after Save Config. Turn on Debug log, reload the checkout and look at the Log field in the Advanced section. It shows OAuth errors (check the Client ID, Client Secret and Test mode (CIE)), 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.

Tax is charged on top of the UPS rate: UPS rates are quoted without taxes. Magento adds tax on shipping only if Tax Class for Shipping is set.

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

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

For developers: the Magento events 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.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_UpsShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_UpsShipping to remove the data, then bin/magento module:disable Vibefox_UpsShipping, delete the folder app/code/Vibefox/UpsShipping and run bin/magento setup:upgrade.

The license key, the license status and the cached UPS token and rates are always removed. If Remove data on uninstall is Yes, the UPS settings and the log are removed too. If it is No, the settings are kept for a re-install. Orders and the UPS services saved with them always stay.

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