/ 
Business-CanadaPost-1.07
River stage zero No dependents
/ README.mkdn

NAME

Business::CanadaPost - Fetch shipping costs for Canada Post (DEPRECATED)

VERSION

version 1.07

SYNOPSIS

    use Business::CanadaPost;
    
    #initialise object - specifying from postal code, and canada post merchant id
    my $shiprequest = Business::CanadaPost->new(    merchantid => 'CPC_DEMO_XML',
                                                    frompostal => 'M1P1C0',
                                                    testing    => 1                 );

    # add an item to be shipped
    $shiprequest->additem(quantity          => 1,
                            height          => 60,
                            width           => 15,
                            length          => 60,
                            weight          => 7,
                            description     => 'box o stuff',
                            readytoship     => 1);

    # set more parameters on the item being shipped
    $shiprequest->setcountry('United States');
    $shiprequest->setprovstate('New York');
    $shiprequest->settopostalzip('11726');
    $shiprequest->settocity('New York');
    $shiprequest->getrequest() || print "Failed sending request: " . $shiprequest->geterror() . "\n"; 
    print "There are " . $shiprequest->getoptioncount() . " available shipping methods.\n";

DESCRIPTION

DEPRECATED: The service this module is an API will be decommissioned as of September 2025 (see https://sellonline-cybervente.canadapost-postescanada.ca/index-e.html).

Business::CanadaPost is a Perl library created to allow users to fetch real-time options and pricing quotes on shipments sent from Canada using Canada Post.

To get off of the development server, you'll need to get an account from Canada Post's "Sell Online" service. While testing, use user id CPC_DEMO_XML and specify a parameter of 'testing' with a value of 1 to the new() constructor, so it knows to use Canada Post's devel server. If you don't, and don't have an account, you'll only receive errors.

PREREQUISITES

This module requires strict, Exporter, and LWP.

EXPORT

None.

CONSTRUCTOR

new(options)

Creates a new Business::CanadaPost object. Different objects available are:

OBJECT METHODS

Most errors are fatal. The tool tries to guess for you if a value seems out of whack.

geterror

Used to fetch the error set when a function return 0 for failure.

Example:

    $object->getrequest or print "Error: " . $object->geterror() . "\n";

setlanguage

Used to change the language.

Example:

    $object->setlanguage('fr'); # changes messages to french.

settocity

Specifies city being shipped to.

Example:

    $object->settocity('New York');

settesting

Specifies whether account is in testing.

Example:

    $object->settesting(1);

setcountry

Specifies country being mailed to.

Example:

    $object->setcountry('United States');

setmerchantid

Specifies Canada Post merchant ID.

Example:

    $object->setmerchantid('CPC_DEMO_XML');

setunits

Specifies imperial or metric measurements.

Example:

    $object->setunits('imperial');

setfrompostalcode

Specifies postal code item is being shipped from.

Example:

    $object->setfrompostalcode(''); # will reset postal code back to default set in canada post profile

settopostalcode

Specifies postal code/zip code item is being shipped to.

Example:

    $object->settopostalcode('N2G5M4');

setprovstate

Specifies province/state being shipped to.

Example:

    $object->settopostalcode('Ontario');

setturnaroundtime

Specifies turnaround time in hours.

Example:

    $object->setturnaroundtime(24);

settotalprice

Specifies total value of items being shipped.

Example:

    $object->settotalprice(5.50);

additem

Adds an item to be shipped to the request.

Example:

    $object->additem(length => 5,
                     height => 3,
                     width  => 2,
                     weight => 5,
                     description => "box of cookies",
                     readytoship => 1,
                     quantity => 1);

Weight, length, height, and width are the only requirements.

If not specified, quantity will default to 1, readytoship will default to 0, and description will default to an empty string.

getrequest

Builds request, sends it to Canada Post, and parses the results.

Example:

    $object->getrequest();

returns 1 on success.

getoptioncount

Returns number of available shipping options.

Example:

    my $available_options = $object->getoptioncount();

getsignature

Returns 1 or 0 based on whether or not a signature would be required for these deliveries.

Example:

    my $signature_required = $object->getsignature();

getinsurance

Returns 1 or 0 based on whether or not extra insurance coverage is required (and included) in prices.

Example:

    my $insurance_included = $object->getinsurance();

getshipname

Receives an option number between 1 and $object->getoptioncount() and returns that option's name.

Example:

    print "First option available is: " . $object->getshipname(1) . "\n";

getshiprate

Operates the same as getshipname, but returns cost of that shipping method.

Example:

    print "First option would cost: " . $object->getshiprate(1) . " to ship.\n";

returns 1 on success.

getshipdate

Operates the same as getshipname, but returns assumed shipment date.

Example:

    print "Item would be shipped out on " . $object->getshipdate(1) . "\n";

getdelvdate

Operates the same as getshipname, but returns when the approximate delivery date would be based on a shipping date of $object->getshipdate();

Example:

    print "Assuming a delivery date of " . $object->getshipdate(1) .
            ", this item would arrive on: " . $object->getdelvdate(1) . "\n";

getdayofweek

Operates the same as getshipname, but returns which day of the week $object->getdelvdate() lands on numerically. (1 .. 6; 1 == Sunday, 6 == Saturday)

Example:

    print "Your item would likely be delivered on the " .
            $object->getdayofweek(1) . " day of the week.\n";

getnextdayam

Operates the same as getshipname, but returns whether or not the current option provides for next day AM delivery service.

Example:

    printf("This item is %savailable for next day delivery\n",
                    $object->getnextdayam(1) == 1 ? '' : 'NOT ');

getestshipdays

Operates the same as getshipname, but returns estimated number of days required to ship the item.

Example:

    print "This shipping method would take approximately: " . $object->getestshipdays() .
            " days to arrive.\n";

getconfirmation

Returns whether or not delivery confirmation is included in price quotes.

Example:

    my $confirmation_included = $object->getconfirmation();

getcomments

Returns any extra comments Canada Post might include with your quote.

Example:

    my $extra_info = $object->getcomments();

SEE ALSO

For more information on how Canada Post's XML shipping system works, please see http://206.191.4.228/DevelopersResources

AUTHORS

COPYRIGHT AND LICENSE

This software is Copyright (c) 2025, 2011 by Justin Wheeler.

This is free software, licensed under:

The GNU General Public License, Version 2, June 1991