Opentaps Shipping Setup

From Opentaps Wiki
Jump to navigationJump to search

opentaps can access the web API's for UPS, US Postal Service, DHL, and Federal Express. To use opentaps with these shipping services, contact your representative and obtain the necessary shipping credentials. Then edit the file applications/product/config/ and modify them as needed.

Also refer to Orders with Drop-Shipped Items, and Configuring Products for Drop Shipping.

IMPORTANT NOTE: For external shipping rate estimates services to work properly, you must configure warehouses with the correct ZIP code. The postal address of your warehouse must also have the purpose "shipping origin address" associated with it.

Follow these directions to set up the connection between open tabs and your shipping service provider, then follow the instructions from setting up your online store to set up your store's shipping options.

Setting up US Postal Service

You can register for an shipping API key on the USPS Web Site. There you can also apply for permission to use the Address Validation API on the USPS API Request Page, so that you can set up opentaps for address validation.

USPS may ask you to test your service. If so, see USPS Rate Calculator Setup for their specific instructions on how test it. Note that the USPS testing URL can only accept certain pre-set zip code and weight combinations. The only production URL which seems to work with RateV2Request is Finally, USPS service classes other than “Parcel” require a container type to be specified for rate estimation.

Once you have the production API keys, you will need to modify the file applications/product/config/ to set the USPS webtools key and the production access URL.

When trying to get USPS rate estimates, make sure that you do not pass a <Container> tag in your string if you are requesting a rate for the Express and the Priority. Otherwise, you will get error messages like: "Invalid container type. Valid container types for Priority Mail are Flat Rate Envelope and Flat Rate Box." or "Valid container type for Express Mail is Flat Rate Envelope." See USPS Rate Estimate API.

Setting up UPS Shipping

Shipping with UPS Online Tools

opentaps supports the UPS Online Tools for many UPS services, including rate checking and shipping. You will need your UPS account number, license key number, and user ID and password. Edit the file application/products/config/ and put those attributes there.

If you want to schedule shipments with UPS, ou must be approved to use the Premium Shipping Tools from UPS. Otherwise, you will not be able to generate labels with opentaps. If when trying to schedule a shipment with UPS in opentaps you see the error:

 An error occurred [code:250003] with severity Hard: Invalid Access License number.

then your shipping credentials have not yet been approved for online shipping.

If you need to send XML samples to UPS for certification, you can configure opentaps to save your UPS XML for you. The path is configured in application/product/config/ under and

Shipping with UPS World Ship

UPS also offers a tool called WorldShip, which is a desktop shipping tool that runs on a Windows PC and prints labels to an attached printer. To integrate opentaps with WorldShip, follow these steps:

  1. Set up an ODBC connection on the WorldShip PC to the opentaps database
  2. Connect WorldShip to the opentaps database via the ODBC connection
  3. Map the following tables and fields in opentaps to your WorldShip fields:
    1. Set SHIPMENT_ROUTE_SEGMENT.SHIPMENT_ID as the import key
    2. Define a relationship between SHIPMENT_ROUTE_SEGEMENT and SHIPMENT using SHIPMENT_ID from both tables
    5. The order ID for your shipment can be obtained from SHIPMENT.PRIMARY_ORDER_ID
    6. The address can be obtained from POSTAL_ADDRESS
    7. The phone number can be obtained from TELECOM_NUMBER

You can then use the shipment ID as the "Import Key" in WorldShip to obtain shipment data from opentaps.

Cash On Delivery (COD)

A UPS shipment can be set up as COD if the only payment method for the order of the shipment is COD, and you have enabled COD in application/products/config/ by setting the flags. The COD amount will be the value of the order plus the COD surcharge you have configured. When you receive a check for all your COD shipments, you can use the Receive COD Statement Screen.


If you need to insure your your shipments, you can configure it in hot-deploy/warehouse/config/ When your shipment is packed, it would check each package of the shipment, add up the value of all the order items in that package, and check that value against the configured minimum insured package value from If this value exceeds the minimum, it will set the shipment package's insured value fields to the value of that package. Later, when your package is actually scheduled with UPS, if there is an insured value for your package, it will add the insured value to the UPS shipment XML.

If you do not have actual weights defined for your products, the UPS rate estimate routine will not generate the right XML, and you may get this error:

<ErrorDescription>The XML document is well formed but the document is not valid</ErrorDescription>

In particular, shipping package weights may have to be integer values.

Setting up Federal Express

To use opentaps with FedEx, you would first need to register for a meter number by calling the fedexSubscriptionRequest request with a contact person name and the partyId of your company. Then, edit the file applications/product/config/ and put in the meter number and your account number. You should now be able to create shipments with FedEx and schedule them on the FedEx test server. Note that the FedEx test server will return a label with test addresses for express service but real addresses for ground service.

Once you're satisfied, change the FedEx URL setting in applications/product/config/ to the production URL, and you should be able to schedule real shipments with FedEx.

If you plan to use FedEx to get rate estimates, you also need to configure the drop off and package types in

Setting up DHL

DHL is handled with DHL ShipIT and is only available for US domestic shipments.. You will need to register with DHL and obtain a userid, password, and a shipping key. You will also need to set your DHL 9-digit account number. Finally, you must specify the format of the label image (GIF or PNG). For compatibility with XSL:FO, we recommend that you use PNG. There is a dhlRegisterAccount service which can help you register your account and obtain a shipping key from DHL.

Setting up Live Rate Estimates

To set up live rate estimates for your shipping methods, update the ProductStoreShipmentMeth entity and fill in the value of the serviceName field with the following services:

* UPS - upsRateEstimate
* FedEx - opentaps.fedexRateRequest
* DHL - dhlRateEstimate
* USPS - uspsRateInquire

This could be most easily done with a SQL query:


IMPORTANT WARNING - Live rate estimates depend on the availability of the carrier's web servers, which may be slow or unavailable at times. If this were to happen, your users might see "Rate Not Available" or a 0 or -1 for the shipping estimate, and they will be able to create an order with no shipping charges. You would have to later modify the order and manually enter a shipping charge.

Using Automated Scheduling << Manual pages >> Fulfilling Drop-Shipped Orders

Inventory Tab << Tab pages

Inventory Processes << Section pages >> Warehouses Organization