UPS I-Parcel Integration#

Overview#

UPS i-parcel is a complete solution to international shipping including showing total landed cost to the customer during checkout, fulfillment, currency conversion and payment. This UPS i-parcel module offers three options for providing customers international shipping and payment options. The Shipping Only operation mode will return all valid international shipping rates for the basket. The second option is Shipping & Payments, which will not only supply valid international shipping rates but uses UPS i-parcel as a hybrid payment method within the Miva store. Finally, iCart or International Cart allows for international customers to checkout using UPS i-parcel’s hosted cart and checkout pages.

Installation & Setup#

To install the i-parcel module, first download it from the Miva App Store.

Next, upload it to the store under Settings -> Domain Settings -> Modules -> Add/Remove Modules.

To make it live, the module needs to be installed on the store. Under Settings -> Modules -> Add/Remove Modules, choose install on the i-parcel module.

Module Configuration#

Public Key: The public key is found in the i-parcel interface under the integrate section.

Note

The public key is only available in Live Mode. When in development mode use the Private Key for this field.
Private Key: The private key can be found within the i-Parcel interface under the integrate section.

Note

This field is only available in the Live Mode.**
Currency: This setting should be the country currency code that the store will be using, it will default to the store settings currency formatting value upon install.
Default Country of Origin: This setting should be the default currency of origin for all products, it will default to the store settings country code.
Operation Mode: Shipping Only: This mode will display the i-parcel shipping methods activated under the services section. (See UPS i-parcel Shipping Only) Shipping & Payment: This mode will activate the i-parcel shipping methods as well as an i-parcel payment method. The i-parcel payment method can only be selected if using an i-parcel shipping method. (See UPS i-parcel Shipping & Payments) iCart: This mode will allow international customers to checkout using UPS International Cart. (See iCart Installation & Setup)
Handoff Message: This message will appear when transitioning to the i-parcel checkout when using the Shipping & Payment operation mode.
Services: UPS i-parcel shipping methods include: UPS i-parcel Express, UPS i-parcel Select, UPS i-parcel Saver, UPS Express, UPS Standard, UPS Express Plus, UPS Saver.

Update Product Harmonization Code and Country of Origin#

The UPS i-parcel integration has the ability to update product Harmonization Codes and Country of Origin via a custom field that will automatically get added when the module is installed. Navigate to Catalog > Products > Edit Product: > UPS i-parcel to see the product configuration settings.

US Harmonization Code: The harmonization classification code of the item. (Note: If the harmonization code is left blank when the scheduled task is run a default value of ‘000000’ will be added.)
Country of Origin: The ISO code for the country/territory where the item originated. (Note: If the country of origin is left blank when the scheduled task is run the default country of origin is added.)

Both of these settings are importable and exportable via the standard product import/export as custom fields under Data Management > Export Products to Flat File.

Update Customer Tax ID#

This setting is only required for customers with shipments to Brazil, Israel, Korea, Russia, South Africa, and Taiwan. These countries require a “ControlNumber” (Tax ID) field to get an international shipping cost. The UPS i-parcel integration adds a setting within Customers > Edit Customer: > UPS i-parcel called Tax ID to add this value if necessary.

To allow customers without accounts to supply a Tax ID, an input can be placed on the OCST page within the Customer Fields section.

<input type="text" name="iParcelTaxID" value="" />

Catalog Sync#

When the UPS i-parcel module is installed the UPS i-parcel Catalog Sync scheduled task is added. This task needs to be run in order for all products to be pushed to UPS i-parcel. The UPS i-parcel Catalog Sync scheduled task includes three new settings:

Scheduled Task Configuration#

Max Products: To avoid timeouts it is recommended to use the default of 1000 products.
Max Kits: To avoid timeouts it is recommended to use the default of 1000 kits.
Force Full Sync: When this settings is checked all products will be updated in UPS i-parcel.

Note

Adding or updating products within Miva will automatically trigger the UPS i-parcel Catalog Sync scheduled task.

Product Kits#

All products (and product variants) are imported with the product code or SKU identifier except for product kits. When a product kit is imported into UPS i-parcel the code is created using the MD5 hash of the following information about the kit:

<Master Product SKU/Code (if sku empty)>[:<inventory attribute code>:<inventory attribute template attribute code>:<option code>]

UPS i-parcel Shipping Only#

Shipping (logistics) only mode will allow international shoppers to receive the active UPS i-parcel shipping methods and their fully landed cost for shipping which includes all taxes, duties and shipping charges prior to completing payment. All UPS i-parcel shipping methods can be managed in the Shipping Method Rules section of the Miva admin.

UPS i-parcel Shipping & Payments#

Shipping & Payments mode will allow an international shopper to use UPS i-parcel as a hybrid shipping/payment method within the Miva store. Once the shopper fills their cart and address details, they are given the UPS i-parcel shipping methods and the UPS i-parcel payment method. Choosing the UPS i-parcel shipping and payment combination will direct the user to a secure UPS i-parcel payment authorization form. UPS i-parcel then redirects the shopper back to the INVC page within the Miva store. No additional setup is needed for this operation mode.

Configure Payment Notification in UPS i-parcel#

In i-parcel under the Notifications tab the Thank You redirect, Cancel Redirect and Order Post API endpoint can be setup.

Thank You Redirect

This is not used in shipping & payments and can be left blank.

Cancel Redirect

This is not used in shipping & payments and can be left blank.

Order Feed Type

Miva supports the POST order feed type.

Order Feed Frequency

This should be set to immediately.

Post Settings

Address should be the following URL:

// change mydomain.com with your correct domain name // change my_store_code with your correct store code. All other parameters remain the same. https://MYDOMAIN.COM/mm5/json.mvc?Store_Code=MY_STORE_CODE&Function=Module&Module_Code=iparcel&Module_Function=iParcel_Notification_Payment

Format Settings

The Data Type should be set to JSON.

Username & Password

These fields can be left blank and only used for HTTP authentication.

Note

JavaScript has been added to the OSEL page which only show the UPS i-parcel payment option when a UPS i-parcel shipping method has been selected.

iCart (International Cart) Installation & Setup#

The UPS iCart integration for Miva supports UPS i-parcel’s “International Cart” checkout solution. It allows for international customers to see prices in their local currency as well as checkout using UPS i-parcel’s hosted cart and checkout pages. The look and feel of the UPS i-parcel cart and checkout pages are fully configurable via CSS in the UPS i-parcel control panel (UPS i-parcel Global Access).

The customer will be given a fully landed cost for shipping which includes all taxes, duties and shipping charges prior to completing payment. Payment is made directly to UPS i-parcel in their checkout flow and the order gets pushed into Miva automatically after purchase.

Add Tracking Script to Miva#

After completing the installation and setup of the module and product custom fields the UPS i-parcel CSS and JS will need to be added to our Miva store. These can be found under the Integrate menu within the UPS i-parcel control panel (UPS i-parcel Global Access).

These scripts should be output globally on every page. These scripts can be copied into the Miva HEAD Tag (Head Tag: User Interface > Settings > Head Tag) or use Miva CSS and JS Asset Management tools to serve them.

Note

The publish button must be clicked in the UPS i-parcel menu to get the CSS and JS to render. This is because the CSS can be controlled right from the i-parcel admin, so any changes need to be published before they will be visible. There could be a small delay before published changes become live. Also, keep in mind, in both Test Mode and Live mode changes need to be updated as they have different environments.

Activate IPARCEL_ATTRIBUTE_MACHINE JavaScript Resource#

Upon installation of the module a JavaScript Resource with the code of IPARCEL_ATTRIBUTE_MACHINE was added. When using the Shipping & Payments operation mode this JavaScript Resource should be added to the PROD page.

(function (obj, eventType, fn) {
    if (obj.addEventListener) {
        obj.addEventListener(eventType, fn, false);
    } else if (obj.attachEvent) {
        obj.attachEvent("on" + eventType, fn);
    }
})(window, "load", function () {
    if (typeof MivaEvents == "object") {
        MivaEvents.SubscribeToEvent("variant_changed", function (data) {
            var cb;
            var container = document.getElementById("iparcel-sku");

            if (!container) return;

            cb = function (response) {
                if (response.success && response.data.sku) {
                    newTextNode_EmptyParent(response.data.sku, container);
                }
            };
            AJAX_Call_Module_JSON(cb, "runtime", "iparcel", "iParcel_VariantSKU_Load", {
                Product_Code: data.product_code,
                Variant_ID: data.variant_id,
            });
        });
    }
});

Configure Order Create Endpoint in UPS i-parcel#

In i-Parcel under the Notifications tab Thank You redirect, Cancel Redirect and Order Post API endpoint need to be setup.

Thank You Redirect

This is not used in shipping & payments and can be left blank.

Cancel Redirect

This is not used in shipping & payments and can be left blank.

Order Feed Type

Miva supports the POST order feed type.

Order Feed Frequency

This should be set to immediately.

Post Settings

Address should be the following URL:

<!-- change mydomain.com with your correct domain name -->
<!-- change my_store_code with your correct store code. All other parameters remain the same. -->

https://MYDOMAIN.COM/mm5/json.mvc?Store_Code=MY_STORE_CODE&Function=Module&Module_Code=iparcel&Module_Function=iParcel_Notification_POST

Format Settings

The Data Type should be set to JSON.

Username & Password

These fields can be left blank and only used for HTTP authentication.

UPS i-parcel Welcome Link#

The output of the welcome link can get configured under the Display Settings section in the UPS i-parcel dashboard. This “Welcome Link” is written to the page via JS and allows the user to choose their country/currency.

When clicked it will bring up a popup to change the country.

In the UPS i-parcel Global Access dashboard under Display Settings > Welcome Link an ID or class can be added to tell UPS i-parcel where it should write the welcome link HTML.

UPS i-parcel Design Configuration#

Control over the look and feel of the UPS i-parcel cart and checkout pages can be customized under Display Settings.

Product Page Customizations#

UPS i-parcel needs to know what html elements on the page it should use for:

Price
Add To Cart
SKU

There are configuration settings under Display Setting > Product Page which give have the setting to identify the ID or class attribute for each of these at both the product and category level.

Troubleshooting i#

Cart Integration

If something is not working correctly or more information on the calls happening to UPS i-parcel is needed, use the browser’s developer tools to explore the AJAX calls being called to UPS i-parcel and examine the data passed:

Another helpful tool to force display the UPS i-parcel “Welcome Mat”. Run this command in the browser’s console:

iparcel.settings.showWelcomeMat();

To force change the country for testing append Country=CA as a URL parameter:

http://www.domain.com/mm5/merchant.mvc?Screen=SFNT&Store_Code=STORE_CODE&country=CA

Shipping Labels#

If a UPS i-parcel shipping method is selected when generating shipping labels then a new setting will appear, Force Label Purchase. If the price of the shipping label being generated is different than the shipping total on the order then the ‘Force label Purchase’ is required.

Note

There are two labels that get created for the UPS i-parcel shipping methods.

XML Provisioning#

<Module code="iparcel" feature="shipping">
    <Settings>
        <APIKey>...</APIKey>
        <Currency>USD</Currency>
        <CartHandoff>Yes|No</CartHandoff>
        <EnabledServices>
            <Service servicenumber="115" />
            <Service servicenumber="112" />
            <Service servicenumber="119" />
            <Service servicenumber="207" />
            <Service servicenumber="208" />
            <Service servicenumber="254" />
            <Service servicenumber="265" />
        </EnabledServices>
    </Settings>
</Module>