OVERVIEW

In true e-commerce environment, you usually use more than one of these APIs at the same time. For example, during a checkout, customer may be prompted for a shipping address, because without this you will not be able to provide the customer the most accurate shipping and handling charge. Once you have customer's shipping address, you may want to verify the address using UPS Address Verification Service. If address verifies, you create a package out of the customer's shopping cart, and submit it back to UPS to calculate the rates, or get the list of rates and services available from your address to that of the customer.

For that purpose, we designed Net::UPS to be singleton, and you have to create Net::UPS object at the start of the process. You will not be required to provide your access information any more.

Any classes that require your access information will consult in-memory Net::UPS object. That's how you create Net::UPS object:

    $ups = Net::UPS->new($username, $password, $xml_access_key);

$username and $password are your login information to your UPS.com profile. $xml_access_key is something you were supposed to get from UPS after receiving your Developer's Key.

Above code doesn't try to authenticate the account at this point, thus it never returns an error of any kind. If any of the above information are not correct, you will not find out about it until Net::UPS actually connects to UPS.com.

UPS RATES AND SERVICES

    $package = Net::UPS::Package->new(
        length  => 34,
        width   => 24,
        height  => 1.5,
        weight  => 1
    );

By default Net::UPS uses English system of measurement. If you want to use metric units:

    $package = Net::UPS::Package->new(
        length              =>  70,
        width               => 50,
        height              => 3,
        weight              => 1,
        measurement_system  =>'metric'
    );

Now all the length units are in centimeters, and weight is measured in KG.

You can prepare multiple packages. Just repeat the above procedure for all the packages, before you request a rate from UPS. By doing so you save network resources. For limits on number of packages submitted at single request consult with UPS Online Tools API, for Net::UPS does not enforce any limit.

Before you can submit your package for a rate quote, you have to prepare two more objects, Shipper's (Your) address, and Recipients's (the customer's) address. That's where Net::UPS::Address comes in.

In calculating shipping cost, the only essential part of the address is the destination and origination zip code (for US). So instead of preparing an address object, you could alternatively pass raw zip code string to "rate()" method, like so:

    my $rate = $ups->rate($zip_from, $zip_to, $package);

If you had multiple packages to submit:

    $ups->rate($zip_from, $zip_to, \@packages);

Alternatively, $zip_from and $zip_to can be replaced with instances of Net::UPS::Address class.

If "rate()" fails, it returns undef. Reason for failure can be found by calling $ups->errstr.

On success, return value of "rate()" is an instance of Net::UPS::Rate class. If you passed more than one package, it returns a list of Net::UPS::Rate instances, one for each package. The order of the rates returned correspond to the order of the packages. If you prefer to loose track of the order of packages, you can alternatively consult rated_package accessor method to get to the instance of rated Net::UPS::Package object. Consider the following example, which rates a single package:

    $rate = $ups->rate($zip_from, $zip_to, $package);
    unless ( defined $rate ) {
        die "Couldn't calculate rates for your package: " . $ups->errstr;
    }
    printf("Sending this package will cost you \$%.2f\n", $rate->total_charges);

Following example shows how to rate multiple packages:

    $rates = $ups->rate($zip_from, $zip_to, \@packages);
    unless ( defined $rates ) {
        die "Couldn't calculate rates for submitted packages: " . $ups->errstr);
    }
    while ($rate = shift @$rates ) {
        printf("PKG %d => %.2f\n", $rate->rated_package->id, $rate->total_charges);
    }

See Net::UPS::Rate for details.

More often than not you want to be able to display all the shipping options your customer has to ship particular package. "shop_for_rates()" does just that. It's syntax is identical to that of "rate()", but returns an array of available services, each an instance of Net::UPS::Service class, regardless of the number of packages being rated.

    $services = $ups->shop_for_rates($zip_from, $zip_to, $package);
    unless ( defined @services ) {
        die "shop_for_rates() failed: " . $ups->errstr;
    }
    while ($service = shift @$services ) {
        printf("%22s => \$.2f\n", $service->label, $service->total_charges);
    }

"$service->rates()" returns an arrayref of Net::UPS::Rate instances, for each package. If there's only one package, "$service->rates()" returns an arrayref with a single element.

In the previous example do not confuse "$rate->total_charges()" with "$service->total_charges()". There is a subtle, but very important distinction. "$rate->total_charges()" returns your total cost for shipping a particular package using a particular service. "$service->total_charges()", on the other hand, returns your total cost for shipping all the packages using a particular service. In the case where you're shipping a single package, your "$service->total_charges()" and "$rate->total_charges()" will be identical.

Alternatively, you can rate a single package directly using Net::UPS::Package:

    $rate = $package->rate($zip_from, $zip_to);
    printf("Your package costs \$%.2f to ship to %s\n", $rate->cost, $rate

This envokes "Net::UPS::rate()".

See Net::UPS::Package and Net::UPS::Service for more details.

SPECIFYING SERVICE OPTIONS

While rating, Net::UPS assumes defaults appropriate for a typical retailer. However, not all the defaults might be true about your business.

For example, your rate may be different if you have a daily pickup type, than if you have an occasional pickup. Your rate may be different if you charge all the orders to your UPS account, than if you don't. Your rate can also be determined by your CustomerClassification field.

Opotions discussed in this section allow you to set/unset these options to get the most accurate rate.

service

Specifies service type. UPS Online Tools understands service code, but symbolic names are supported by Net::UPS for ease of use. Available service types are NEXT_DAY_AIR, 2ND_DAY_AIR, GROUND, WORLDWIDE_EXPRESS, WORLDWIDE_EXPDEDITED, STANDARD, 3 DAY_SELECT, NEXT_DAY_AIR_SAVER, NEXT_DAY_AIR_EARLY_AM, WORLDWIDE_EXPRESS_PLUS, 2ND_DAY_AIR_AM. These are all the service types available for US as of this writing. Some of the services originating from outside the US, although have the same name as that of US origin, their codes might be different. Care should be exercised in using Net::UPS if package's place of origin is not US. In these cases service type should be provided in the form of Codes, as documented in UPS Online Tools API documentation

packaging

Specifies type of packaging used. Default is PACKAGE. Additional available options are TUBE, PAK, EXPRESS_BOX, 25KG_BOX, 10KG_BOX. Any other options should be specified in the form of Codes, as documented in UPS Online Tools API.

pickup_type

Type of pickup. Available symbolic values are "DAILY", "OCCASIONAL", "ONE_TIME". Any other values should be specified using their codes as documented in UPS Online Tools API.