X-Cart:UPS Developer Kit

UPS Developer Kit is formerly known as UPS Online Tools.

What UPS Developer Kit module does

The module UPS Developer Kit enables UPS real-time shipping rate calculation at your store.

Roles in UPS Developer Kit module management

If you are an X-Cart GOLD administrator/provider or an X-Cart PRO administrator:

• You can enable/disable UPS Developer Kit module, perform UPS Developer Kit registration and configure the module settings

Enabling and Configuring 'UPS Developer Kit'

To begin using the module:

1. Make sure your store meets the system requirements for installing and using UPS Developer Kit module. The following components are required:

• EXPAT extension for php;
• HTTPS module like Net:SLeay, libCURL, CURL, Open SSL or HTTPS-cli.

Note: You can use the Summary page (Administration menu->Summary) to find out whether these components are installed on your system.

Note: If you select Net:SLeay perl module as your preferred HTTPS module, be sure to specify the full path to Perl interpreter executable in General settings->General options.

IMPORTANT: Make sure the HTTPS module selected as the "Preferred HTTPS module" is working. Non-working HTTPS module may cause "Internal Server Error" and prevent your store from operating properly.

See also:

• How to test HTTPS modules in my X-Cart store?
• UPS Developer Kit & Registration wizard: getting "Internal Server Error" at step 2

2. Enable UPS Developer Kit module (Administration menu->Modules).

When the module is enabled, a link 'UPS Developer Kit' appears in the Settings menu of the Admin area of your store.

3. Register your UPS Developer Kit with UPS:

• Go to the 'UPS Developer Kit' section of your store (Settings menu->UPS Developer Kit). You should see a dialog box titled 'UPS Developer Kit - Main page'.

• Click the Register button. UPS Developer Kit Licensing & Registration Wizard will be launched to guide you through the registration process.

• Complete the registration:

At Step 1, click the button Next to proceed with the registration.

At Step 2, read the UPS Technology Agreement.

If you agree to be bound by the terms and conditions of this Agreement, select 'Yes, I Do Agree' and click on Next. If you do not agree to accept the terms and conditions of the Agreement, select 'No, I Do Not Agree' and click on Next (In this case you will exit the registration process).

At Step 3, provide your registration information. The address you provided in General settings->Company options is automatically entered into the registration form. However, you can provide a different address and contact info (manually or using the Fill From Profile button).

Make sure you have completed all the fields and entered your valid email address before you click the Next button.

Step 4 informs you of the successful completion of the registration process:

Click the Finish button to return to 'UPS Developer Kit - Main page'.

4. Adjust your store to use UPS Developer Kit:

• Ensure that the option 'Real-time shipping calculation' is enabled and the option 'Intershipper calculation services' is disabled in General settings->Shipping options section.
• Again, go to the 'UPS Developer Kit' section of your store. After you have registered your UPS Developer Kit with UPS, a Configure button appears in the 'UPS Developer Kit - Main page' dialog box:

Click this button. A dialog box titled 'UPS Developer Kit Rates & Service Selection' opens.

• Complete the fields in the 'Rates & Service Selection OnLine Tool' and 'Address Validation OnLine Tool' subsections of the 'UPS Developer Kit Rates & Service Selection' dialog box.
• Click the Update button.

Note: The button Test can be used to test the Rates & Service Selection and Address Validation Tools.

Setting up International Shipping

Some of the international shipping services offered by UPS may depend on other UPS services. If you are planning to use such shipping methods in your store, it is important to resolve these dependencies first. Otherwise X-Cart will not be able to estimate UPS shipping charges in the real-time mode.

To resolve the dependencies, you need to activate the generic UPS services along with the shipping methods that you are planning to use. For example, UPS Express Saver (SM) depends on UPS Saver. Therefore, to get shipping charges for UPS Express Saver (SM) estimated you need to activate both UPS Express Saver (SM) and UPS Saver.

To activate UPS shipping services:

1. Log in to the Admin area.
2. Go to the Shipping methods section (Management menu -> Shipping methods).
3. In the 'Shipping methods' box, click on the UPS link to expand the list of available shipping methods.
4. Select the check boxes for the methods you want to activate.
5. Click the Update button.

Important!

Activate "UPS Saver" shipping method if you are going to offer the following methods for your customers:

• UPS Express Saver (SM)
• UPS Worldwide Saver (SM)
• UPS Worldwide Express Saver (SM)

Otherwise these methods will not be available for customers.

Activate "UPS Standard" shipping method to be able to offer the "UPS Standard to Canada" shipping method to customers.

Setting up Dimensional Shipping

X-Cart now provides a packaging algorithm that allows splitting an entire purchase into multiple packages that fit the limitations (maximum package weight and dimensions) imposed by a certain shipping service. This algorithm allows to get real-time shipping rates even when the cart contains a large quantity of products with the total weight and dimensions exceeding the values allowed for a single package.

With the Dimensional Shipping feature, you can specify dimensions for each product you have got at your store (See the Product details page) and use those dimensions for calculating shipping rates using the on-line real-time shipping rate calculation services like UPS, USPS, FedEx, etc.

Module-specific settings

Certain shipping modules, such as Australia Post, FedEx, UPS and USPS allow enabling/disabling splitting orders into multiple packages.

To enable this function, select Split the shipment into multiple packages if its weight/dimensions exceed the limitations on the Shipping methods -> Options page of the administration menu.

In the shipping settings, you can also specify:

Maximum package weight (lbs) - package weight that must not be exceeded when when shipping products to customers.

Maximum package dimensions (inches) - package dimensions that must not be exceeded when when shipping products to customers.

Always use the same package dimensions as specified in the "Maximum package dimensions" fields - applies the dimensions specified in the above option to all packages shipped through this shipping service.

Keep in mind...

• If the total weight/volume of the products ordered by customer exceeds the limitations defined by these settings, the order is split into several packages.

• The maximum package weight and maximum package dimensions that you set on this page must not exceed the actual limitations imposed by the shipping service.

• If you set the maximum package weight or any of the maximum package dimension values to zero, X-Cart will use the default limitations established by the shipping service.

For other shipping modules, please follow the instructions below.

Enabling Dimensional Shipping

To enable Dimensional Shipping:

1. Select Settings -> General settings on the administration menu and then click on the Shipping link on the Сore options pane at the right.

2. On the Shipping page that appears, select the Use product dimensions for shipping rates calculation check box under General shipping options.

3. On the same page, under Dimensions of the shipping box for small items (for real-time shipping), specify the length, width and height (in inches) for the default shipping box. These dimensions are used by the calculator when no product-specific dimensions are provided.

4. Click the Apply changes button.

Note: To enable the shipping calculators, make sure to select the ENABLE SHIPPING check box at the top of the page before making any other shipping settings.

Defining product dimensions

To define dimensions of a product:

1. Sign in as provider and select the product to be edited.

2. On the Product management page, select the Use the dimensions of this product for shipping cost calculation check box.

3. In the Shipping box dimensions group, specify the length, width and height of the product, in inches.

To make sure that UPS supports the dimensions you have specified, click on the Check for unavailable shipping methods link by the dimension boxes.

4. Select the Ship in a separate box option to set shipping the product in separate boxes, then specify the Quantity per shipping box, i.e. how many pieces of the item can be placed in a single shipping box.

5. Click the Apply changes button.

Checking dimensional shipping settings

The following instructions are meant for advanced users.

To check dimensional shipping settings:

1. Open the directory where your X-Cart is installed in a file manager and then open the file config.local.php in any plain-text editor.

Hint! If the file config.local.php does not exist, create a new text file and save it as config.local.php.

2. In the config.local.php file, uncomment or type the following code:

<?php
define("PACKAGING_DEBUG", "Y");
?>

3. Save the modified config.local.php file in the directory where your X-Cart is installed and test your shipping calculator with the new settings.

This constant adds comments on the performance of the packaging routine at the bottom of the UPS calculator page. View those comments in an HTML source viewer and determine whether your dimensional shipping settings work as expected.

When you are done testing, don't forget to comment out or delete the debug string from the config.local.php file.

Hint! An alternative way to check whether your dimensional shipping settings work as expected is to place a number of items greater than what fits in a shipping box to the shopping cart and see how many boxes you have got for shipping.

Troubleshooting

UPS Developer Kit & Registration wizard: getting error "Sorry, license agreement is temporary unavailable. Try again later."

First make sure that your X-Cart copy is registered. To learn how to do this see this article.

When your X-Cart has been registered, perform the following steps:

1. Log in your store back-end.
2. Go to the "Summary" page, "Environment info" section.
3. Check if any HTTPS modules are available and test them.
4. Go to the "General Settings" page.
5. Switch the "Preferred HTTPS module" setting value to any HTTPS module that is available and working on your server (according to step 3).
6. Try to register UPS Developer Kit again.
7. If the error still persists, repeat steps 5-6 until resolved.

Note: If there are no HTTPS modules available, please refer to the "X-Cart:Setting Up HTTPS modules" article.

UPS Developer Kit & Registration wizard: getting "Internal Server Error" at step 2

Please install the patch-improvement provided in this Bugtracker's ticket.

Alternatively, you can try to switch the "Preferred HTTPS module" setting from libCURL to any other HTTPS module that is available and working on your server.

NOTE: The first solution (installing the patch-improvement) is still the most preferred and highly recommended one.

See also:

• How to test HTTPS modules in my X-Cart store?

UPS not showing up as a shipping option for customers during checkout

1) Try to re-register UPS Developer Kit in your X-Cart admin back-end, as described in the Enabling and Configuring 'UPS Developer Kit' section, step 3.

2) Apply the following SQL patch ( wonder how to apply SQL patches?):

DELETE FROM xcart_shipping_cache;

If the problem still persists, please contact our tech support for assistance.

The administartor is logged out when registering at UPS Developer Kit

When trying to register at "UPS Developer Kit" the administrator is redirected to the /admin/error_message.php?access_denied&id=37 page.

The issue is caused by some strange glitch in MySQL due to which the headers were corrupted..

In order to fix the issue add the following code to init.php file:

db_query("set names latin1");

UPS Developer Kit: "There are no shipping methods available" error

X-Cart 4.1.9

Affected version: X-Cart v.4.1.9

Using UPS online shipping, no matter what settings are used in the admin area, the following error message keeps appearing:

"There are no shipping methods available" (http://www.yoursite.com/error_message.php?error_no_shipping) as soon as anyone tries to checkout.

You can then click view cart and see the shipping method selected.

Solution: upgrade your X-Cart up to the 4.1.12 version.

UPS Developer Kit: "Invalid UserId/Password (errorcode: 250002)" error

X-Cart 4.3.2

Affected version: X-Cart v.4.3.2 and older.

When using UPS Developer Kit, the following error message appears at checkout:

"Error:(250002) Invalid UserId/Password"

Solution:

In case the "Use negotiated rates" option is NOT enabled (Settings menu -> UPS Developer Kit -> Configure button), try to re-register UPS Developer Kit in your X-Cart admin back-end, as described in the Enabling and Configuring 'UPS Developer Kit' section, step 3. If the problem still persists, please contact our tech support for assistance.

In case the "Use negotiated rates" option is enabled, please follow the steps described in this article: How to enable UPS Negotiated Rates in my store?

Can not get rates for 'UPS Standard to Canada'

You should enable both 'UPS Standard to Canada' and 'UPS Standard' shipping methods in the 'Shipping Methods' section of the Admin area.

UPS Developer Kit: "The XML document is not well formed (errorcode: 10001)" error

UPS Realtime shipping rate calculation service returns the following error:

The XML document is not well formed (errorcode: 10001)

Solution:

1. First make sure that your X-Cart copy is registered. See Registering installed X-Cart. When your X-Cart has been registered, proceed with the next step.
2. Re-register UPS Developer Kit in your X-Cart admin back-end, as described in the Enabling and Configuring 'UPS Developer Kit' section, step 3.

If the problem still persists, please contact our tech support for assistance.

FAQ

How do I get UPS Developer Kit working on my development server?

My dev server is internal and does not accept external connections. Thus, it is impossible to activate X-Cart license and get UPS Developer Kit working.

Solution:

1) Obtain Developer's Key from UPS.

2) Create config.local.UPS_OnLine_Tools.php file in the X-Cart directory, put the following code in the file:

$devlicense = '{developer_key}';

where {developer_key} should be replaced with your Developer's Key obtained from UPS.

3) Modify the following file in your dev X-Cart installation:

• skin/common_files/modules/UPS_OnLine_Tools/ups.tpl (X-Cart 4.4)
• skin1/modules/UPS_OnLine_Tools/ups.tpl (X-Cart 4.3)

- find the following line of code:

{if $shop_evaluation and $shop_evaluation ne "WRONG_DOMAIN"}

- change it as follows:

{if false and $shop_evaluation and $shop_evaluation ne "WRONG_DOMAIN"}

4) Enable and configure 'UPS Developer Kit' via your X-Cart admin back-end.

How to enable UPS Negotiated Rates in my store?

When you register UPS Developer Kit in your X-Cart store, you will get default credentials (UserID, Password and AccessKey) from UPS. These default credentials are associated with your Shipper Account Number, but do not allow to use negotiated rates, unfortunately.

To enable Negotiated Rates in your X-Cart store, please follow these steps:

a) Make sure your Shipper Account Number is qualified for Negotiated Rates. Please contact UPS for assistance in getting your Shipper Account Number approved for Negotiated Rates.

Once your Shipper Account Number is qualified for Negotiated Rates, proceed with the next step.

b) Find the following lines in the "<xcart_dir>/shipping/mod_UPS.php" file:

$UPS_username = text_decrypt(trim($config["UPS_OnLine_Tools"]["UPS_username"]));
$UPS_password = text_decrypt(trim($config["UPS_OnLine_Tools"]["UPS_password"]));
$UPS_accesskey = text_decrypt(trim($config["UPS_OnLine_Tools"]["UPS_accesskey"]));

and replace them with these lines:

$UPS_username = "UserID";
$UPS_password = "Password";
$UPS_accesskey = "AccessKey";

Where "UserID", "Password" and "AccessKey" are corresponding UserID, Password and AccessKey qualified for Negotiated Rates and associated with your Shipper Account Number. Please contact UPS to obtain these credentials.

See also

• Setting up Dimensional Shipping