Integration Guides
Tax Services
TaxJar
Avalara
Fraud Tools
Signifyd
Kount
Payments
Apruve
Affirm
Shipping
UPS i-Parcel
Advanced Shipping Manager
Order Management
Stone Edge Order Manager
ShipStation
4psite
Rewards & Loyalty
Zinrelo Loyalty & Rewards
Miva Points & Loyalty Program

UPS i-parcel

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 Modules > Add/Remove Modules.

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

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

Catalog > Products > Edit Product: > UPS i-parcel

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.

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:

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:

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.

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

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:

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 iCart 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:

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.