Ubercart Stamps.com Shipping Labels

This module allows you to use the Stamps.com software to print United States Postal Service (USPS) shipping labels from Ubercart. It is an Ubercart shipping method that imports and exports Stamps.com XML files for batch processing.

As of this writing (March 2013), this module is currently the only open source method for printing USPS shipping labels for Ubercart orders

Packages and shipping options are very configurable. The module has enough intelligence to automatically select and export the correct package information to Stamps.com most of the time. This is intended to reduce the amount of human work required to perform shipping functions.

Requirements

This module requires Ubercart version 7.x-3.4 or higher. Printing labels requires an account with Stamps.com and the Stamps.com software, which runs on Microsoft Windows.

Installation

>

This module is installed like any other. Download it from the project page. Make sure to run the update.php script after installing or updating it.

Configuration

Configuring this module involves describing how your business ships packages. It might take some work to enter all the information before you can get started shipping, but the module uses the information later to automate your shipping and reduce the amount of manual work and calculation required.

Configure shipping containers

First, describe your shipping containers at the container configuration page (admin/store/settings/stamps/container). Containers are simply the boxes or other objects your business uses to package products for shipment. For each container your business uses for shipping, enter the following:

Container name

This is simply the name of the container that you will see when configuring and using this module.

Container type

Select the USPS type of container. Select "Small Shipper-Supplied Package" for most containers. If your business uses packaging supplied by USPS, select one of the flat-rate containers. See USPS Mailpiece Types for details about the different package types.

Priority

Enter the priority for this container. When building a shipment, this module first finds all the containers that are big enough to hold the products in the package. If multiple containers are available, this module will select the one with the highest priority. It is usually a good idea to give the smaller containers a higher priority. That way, if an order can fit into either a big box or a small box, this module will choose the smaller one.

Capacity

Enter the capacity of the container. This is the maximum weight it can hold. This module uses the capacity to select which container to use when building a shipment.

Tare

Enter the tare weight of the container. This is the weight of the container and any packaging, tape, or documents it uses, not including the actual products. This module needs this information to calculate the actual gross weight of packages. This is optional for flat-rate containers.

Length, Width, and Height

Enter the length, width, and height of the container. This is optional for most containers, but required for container types "Large Shipper-Supplied Package" and "Oversize Shipper-Supplied Package".

Box-shaped

Select this checkbox if the container is a standard box shape. Uncheck it for unusually-shaped (non-machineable) containers.

Configure shipping modes

Shipping modes are the combinations of shipping classes and options used to ship a package. For instance, Priority Mail with COD, Delivery Confirmation, and Stamps.com insurance is one possible mode. Create all the common shipping modes your business uses. Note that the options can be manually overridden when creating shipments.

Enter your shipping modes at the Shipping Modes configuration page (admin/store/settings/stamps/mode). For each mode your business uses, click on "Add a shipping mode" then fill in the following fields:

Mode name

Fill in the human-readable name for this mode.

Shipping class

Fill in the shipping class for this mode. See Domestic mail classes and International mail classes for information about the different mail classes available.

Service options

Fill in the USPS shipping services (options) you wish to use. The available services are dependent on the shipping class and other options already selected. See About USPS Special Services for a list of service options.

Default container

Select the container to use when the module is creating a shipment but cannot find a viable container to use. This typically happens when a package is too heavy for any of the available containers.

Available containers

Select the containers that are available for this shipping mode. When creating a shipment, the module will select the highest-priority container selected here with enough capacity to hold the weight of the products in the package.

Priority

Select the mode's priority. If multiple modes are valid for creating a shipment, this module will select the mode with the highest priority.

After creating a mode, the module brings up a Rules condition page. Enter the conditions under which the new mode can be used. Usually, the conditions will involve the "Order has a shipping quote from a particular method" condition.

Configure global options

Once all your modes are entered, go to the Stamps.com settings page (admin/store/settins/stamps) and set global options for the module. The options are self-explanatory.

Configure customs information

If your business ships internationally, enter customs information for your products.

The USPS requires customs forms for packages shipped internationally. The Stamps.com software generates these forms, but it needs some customs information to do so. The customs information is just a short description of the product, the country of origin of the product, and an optional tariff code. There are three ways to enter this information.

Individual product

Each product can have individual customs information.

1. Edit an individual product (content) node.
2. Scroll to the bottom of the edit page and click on the "Shipping settings" vertical tab.
3. Click on the "Stamps.com Customs Information" line to expand it.
4. Enter the customs information there and save the form. Leave these fields blank to use the default product class or store customs information.

Product class

Each product class can have customs information. When set, product class customs information applies to all products of that class. The customs information can be overridden on a per-product basis.

1. Go to the store product type administration page. (admin/store/products/classes)
2. Click on the "edit" link for the product class that needs customs information.
3. Click on the "Stamps.com" tab.
4. Enter the customs information there and save the form. Leave the "Country of origin" field set to "- Default -" to use the store default country of origin.

Store default

The store default country of origin is used for products with no country of origin set for either the product class or the product itself. To set it:

1. Go to the Stamps.com settings page (admin/store/settings/stamps).
2. Select the Default Country of Origin and save the form.

Use the Stamps.com software

If you do not specify customs information for a product, the Stamps.com software will prompt you for it when you print a shipping label.

Set up a Stamps.com import interface

The module is now ready to export XML files to the Stamps.com software and import postback information. Before you can do that, though, you must set up the Stamps.com software and configure it with a batch interface. These directions assume you have the Stamps.com software already set up. See the Stamps.com Startup Guide if you need help.

There are two kinds of Stamps.com XML interfaces: XML directory monitoring and XML batch interface.

XML directory monitoring

This watches a directory you specify. When you place an XML file in that directory, the Stamps.com software immediately reads the file, prints the labels, and writes out a postback file. See XML directory monitoring for details.

An XML batch data source

Upon user prompting, Stamps.com reads in a specified XML file and allows you to review and modify the labels before printing them. See XML batch data source for details.

Processing shipments

This section explains the basic operations of using this module and the Stamps.com software: How to process packages and shipments, export label information, print labels, and post back shipment information.

Preparing shipments

Before an order's shipping label information can be exported to Stamps.com, you must use Ubercart to organize the ordered products into packages, then organize the packages into shipments. Start the process at Ubercart's View orders page (admin/store/orders/view). See Ubercart's documentation for further details.

An Ubercart package is a group of products from an order that should be shipped together in a single container.

An Ubercart shipment is a group of packages from an order that should be shipped together with the same origin, destination, carrier, shipping class, and options.

With the current version of Ubercart, you must manually create packages and shipments for each order; this process can be labor-intensive if you have a lot of orders. Still, it's much better than copy-and paste. There is an effort underway to overhaul Ubercart's shipping and automate some of this process. See the issue if you can help. This is a major project, and help is needed, including testers.

Create packages

For each order you you wish to export to Stamps.com, click on the little icon with a picture of a green arrow pointed at a box or the order's "Packages" tab. This brings you to the packaging screen for that order. Organize the products into packages. If you wish to ship the whole order in one box, just select all the products and click "Create one package".

Create shipments

Once the order's products are organized into packages, create a shipment or shipments from those packages.

1. Click on the order's "Shipments" tab or the little "Ship order" icon to bring up the shipments page with a list of unshipped packages.
2. Select the packages to place in the new shipment.
3. For "Shipping method," choose "Stamps.com shipping labels".
4. Click "Ship packages" to bring up the shipment editing page.
5. All of that earlier container and mode configuration pays off here. The Stamps.com module automatically fills in the shipping details, including the containers, shipping class, and service options. Review the shipment to make sure everything looks correct.
6. If everything looks good, click on "Enqueue shipment for batch". This enqueues all the packages in the shipment for export to Stamps.com.

Exporting package information from Ubercart

Once all the shipments and their packages have been enqueued for batch, they can be exported. The module sends an XML file to your Web browser, which you can use to download the file.

1. Go to the Stamps.com Export/Import page using the computer that has the Stamps.com software installed. This page lists all the queued packages.
2. Click on the "Export to Stamps.com" button. The module generates an XML file and sends it to your browser.
3. Save the XML file to the appropriate file name or directory as configured in the Stamps.com XML Batch or Directory monitoring.
4. Reload the Stamps.com Export/Import page in your browser (this cannot be done automatically). The exported packages will now be listed as "exported packages".

Importing package information to Stamps.com

Once the data is exported from Ubercart, import it into Stamps.com. This is not required when using directory monitoring. Perform the following steps in the Stamps.com software:

1. Click on "Batch" in the left navigation bar. The batch screen appears.
2. Click on the XML data source you set up earlier.
3. Click "Import Orders" on the control bar at the top-left of the Batch window. The software will import the orders you saved to an XML file earlier. The Stamps.com software may prompt you to fix addressing or other issues.

Printing labels

Once you have imported package information into Stamps.com, you can print the labels. See XML batch data source for full details. This step is not required for XML directory monitoring. For basic printing:

1. Click on "Select all" (center top).
2. Click "Print". The labels will print.

Exporting postback information from Stamps.com

Once the labels are printed, export postback data from the Stamps.com and import it to Ubercart. This postback information contains tracking numbers and shipping costs. This step must be done immediately after printing labels, or the information is lost.

This step is done automatically when using XML directory monitoring. Stamps.com automatically exports a usable XML postback file. For an XML batch data source, the process is manual:

1. Click on the "printed" line for your XML batch data source.
2. Click on "Export" and select the "CSV" file format. Do not export XML. The batch XML postback files do not contain enough postback information.
3. Select a file name and save the CSV postback file. Make sure it ends with ".csv".

Importing postback information to Ubercart

Once you have a postback file from Stamps.com, import it to Ubercart to get the tracking numbers and shipping cost information for each package. The postback file will be an XML file for directory monitoring, or a CSV file for the batch interface.

1. Return to the Stamps.com Export/Import page. (admin/store/orders/stamps)
2. Click on the "Browse" button.
3. Select your postback file.
4. Click the "Upload" button. This uploads the file to your Drupal Web site.
5. Click on the "Post back from Stamps.com button. The file is processed. All the packages posted back should disappear from the page.