Shipping
========

Shipping Module Activation
--------------------------

Satchmo provides you the flexibility to enable and disable as many shipping modules
as you would like.  Since everyone has different needs for shipping, there's a simple
but powerful way to define your own shipping modules.

Activate and configure your shipping modules from your site settings page.
Usually this is at ``SHOP_BASE/settings/``. You can also access this page from
the ``Edit Site Settings`` link on your main admin home page.

.. Note::
    If you have custom modules you would like to add, make sure it is added to your
    ``CUSTOM_SHIPPING_MODULES`` list in your local_settings.py file

Available Modules
-----------------

Satchmo includes several modules in the default distribution.

Dummy
^^^^^

This module is mainly included in order to demonstrate how you can create your own modules.  If
you have an interest in creating your own, copy this module to a new directory and use the comments
to guide you through the process.

Flat
^^^^

This is a very simple module that allows you to set a flat rate for all shipments.  It's not very
sophisticated but it may be useful for simple stores or as a basis for other modules.  The values
can be configured through your settings page.

Per
^^^

This module is a little bit more complex than the flat rate.  It allows you to set one rate that is
multiplied by the number of items in your order.  These values are configured through your settings
page.

Tiered
^^^^^^

This one is much more flexible than any of the prior modules, so it requires a little more configuration.
It is not enabled by default.

To enable:

 1. Add shipping.modules.tiered to your settings.py INSTALLED_APPS and then run syncdb.
 2. Enable in site settings under "Active Shipping Modules"
 3. Configure using the administration page like you would a product.

Why bother?

Well, it allows you to set up multiple carriers, for one thing.
For another, you can have different prices based on cart total (total of shippable items, to be specific).
For another, it is multilingual from the start, with you being able to specify translations of carrier,
method, etc. right in the admin pages.  Lastly, you can have shipping specials, expiring on the dates
of your choice.

For example, you can make this shipping table::

    $0-$25   UPS=$8.50, Fedex=$18.00
    $25.01-$50 UPS=$9.75, Fedex=21.00
    ....
    $250.00 + free

.. index::
   single: UPS

TieredWeight
++++++++++++

This module provides similar features to tiered and requires the same extra steps to install. In addition
you can specify a number of zones for each carrier adding a number of countries to each zone. You can then
choose a default zone for each carrier. Each zone can have a number of cart weights with corresponding
price and handling fee. This means that at checkout the shipping price is based on the shipping country
and the total weight of the cart.

UPS
^^^

The UPS shipping module provides an interface to the UPS Rating and Service selection interface.  This service
from UPS allows you to get custom real time shipping quotes based on the sending and receiving addresses
as well the items in the shipment.

The Satchmo module uses the XML interface which provides maximum flexibility. The UPS interface is very
robust and allows many complex actions. Satchmo is configured to support a basic configuration. If you choose
to use this service, you should review the UPS developer documents (available when you sign up) and verify
that the shipping configuration currently used by Satchmo makes sense for your needs.

Before you attempt to test the UPS module, you must sign up for a developer account at the
`UPS web site <http://www.ups.com/content/us/en/bussol/offering/technology/automated_shipping/online_tools.html>`_.

To enable:

 1. In your site settings, make sure that the UPS shipping module is active
 2. Configure the UPS settings as described below.
 3. Make sure your store mailing address is correct in the Store Configuration

You must configure the following settings in the Site Settings -> UPS Shipping Settings:

 - Type of packaging used by your store (refer to UPS docs for details)
 - Your UPS account number
 - UPS Pickup option
 - Shipping choices you wish to offer to your customers
 - UPS user ID
 - UPD user password
 - UPS XML Access key

Refer to the UPS developer documentation for more definitions on these options.

The UPS api is very powerful and does extensive validation on the data being submitted. Depending on your configuration,
a number of possible errors could be returned by the UPS servers. For many of these errors, Satchmo chooses to silently
ignore the UPS option that has an issue. The design philosophy is that it is better to not present a price than to present one that may be
inaccurate.  For this reason, it is strongly encouraged that you have at least one other shipping module enabled so that
if there is an error, your customer will still be able to successfully complete the checkout process. To view any errors
that may have been generated by the UPS module, please refer to the satchmo log stored in the location specified in your
local_settings.py file.

The shipping module does rely on the weight and dimension data you have entered for your products. If you have not
entered the weight, then the module will not display any choices.

One important note to remember with the UPS module is that when a user has multiple products in the cart, the UPS request
will quote this as if each product is shipped in a separate package. For example, two 3 pound packages will cost more to ship than
one 6 pound package. If your shop has a different method of shipping, you will need to override the 
/apps/shipping/templates/shipping/ups/request.xml file to group products together into one package.

.. index::
   single: Fedex;

Fedex
^^^^^

The Fedex module allows Satchmo to calculate shipping costs using the Fedex Web Services interface.

One important note to consider is that each product MUST have a weight of at least .1 pounds for Fedex to give a valid response.
If you have a configurable product you will need to set weights on each product option. Otherwise you will get errors when the
FedEx module tries to calculate the weight to send to FedEx for the quote.

To enable in Satchmo:

 1. In your site settings, make sure that the Fedex module is active
 2. Configure the settings as described below

Once you've got the module installed its time to get your account set up with FedEx. (It does not work without the following steps)

 1. Go to http://www.fedex.com/us/developer/
 2. Log in (you may need to create an account) and go to technical resources. https://www.fedex.com/wpor/web/jsp/drclinks.jsp?links=index.html
 3. Click "Get Started with FedEx Web Services Technical Resources now"
 4. Click "Move to Production"
 5. At the bottom click "Get Production Key"
 6. Answer the questions / Fill out the forms. Note: You will need a FedEx account number.
 7. Save your authentication key and meter number.
 8. Add your meter number to the shop settings after enabling the FedEx shipping module.
 9. Check the box to connect to the production server.

.. index::
   single: USPS;
   
USPS
^^^^

The United States Postal Service module allows you to calculate shipping costs using the USPS web api. Here are a couple of noted
regarding this module:

 - The USPS API won't return shipping rates if you are trying to go against the testing server, 
   so a couple of the settings in modules/config.py become useless and confusing
 - Make sure your products have weights associated with them. The USPS API won't accept weightless packages and your 
   list of shipping options might not be a list at all!
 - The module assumes that the value entered in a product's "weight" attribute is in pounds (because that's what USPS expects)
 - Some rates such as parcel post automatically include the "additional postage may apply" values, and according to 
   exchanges with the USPS support crew, we just have to deal with it.
   
To enable in Satchmo:

 1. In your site settings, make sure that the USPS module is active
 2. Configure the password and package settings

Canada Post
^^^^^^^^^^^

Prerequisites

  - You must specify dimensions and weight for the products you intend to ship using Canada Post.

  - You must have a merchant id assigned by Canada Post to  use the module in production environment. Visit
    http://www.canadapost.ca/business/default-e.asp for more information.


Setting Up

  - Open up Satchmo settings at http://example.com/settings

  - Click on "Show" next to "Shipping Settings"
  
  - Save.

  - Click on "Show" next to "Canada Post Shipping Settings"
    to configure the module according to your needs.

  - Save.

Notes

  - Turn around time is the average time that you will take 
    to process an order before it is ready for Canada Post
    to pick it up. It may include inventory sourcing, payment
    processing, order packing, etc. Canada Post will add 
    this time to the shipping date and quote the delivery date
    based on that.


  - For "Type of container used to ship product" select "Unknown"
    if you are not sure. If shipping single product Canada post 
    will find smallest box available and if shipping multiple 
    products it will "find the most cost-effective box combination.
    http://www.canadapost.ca/business/offerings/sell_online_shipping_module/can/demo_5-e.asp


Hide Shipping if One Module
^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you store only has one shipping option, then you may prefer not to show any ability to select shipping options. There is a 
setting in /settings that allows you to control this behavior.
