number
: The unique identifier for this shipment. It begins with the letter H and ends in an 11-digit number. This number is shown to the users, and can be used to find the order by calling Spree::Shipment.find_by(number: number)
.tracking
: The identifier given for the shipping provider (i.e. FedEx, UPS, etc).shipped_at
: The time when the shipment was shipped.state
: The current state of the shipment.stock_location_id
: The ID of the Stock Location where the items for this shipment will be sourced from.pending
: The shipment has backordered inventory units and/or the order is not paid for.ready
: The shipment has no backordered inventory units and the order is paid for.shipped
: The shipment is on its way to the buyer.canceled
: When an order is cancelled, all of its shipments will also be cancelled. When this happens, all items in the shipment will be restocked. If an order is "resumed", then the shipment will also be resumed.Zone
. For example, you wouldn't be able to get a package delivered internationally using a domestic-only shipping method. You can't ship from Dallas, USA to Rio de Janeiro, Brazil using UPS Ground (a US-only carrier).Configuration
-> Shipping Categories
) and then assigned to products (Products
-> Edit
).Shipment
objects are created during checkout for an order. Initially each records just the shipping method and the order it applies to. The administrator can update the record with the actual shipping cost and a tracking code, and may also (once only) confirm the dispatch. This confirmation causes a shipping date to be set as the time of confirmation.LineItem
objects and return a cost. It can look at any reachable data, but typically uses the address, the order and the information from variants which are contained in the line_items.ShippingCategory
, which adds product-specific information to the calculations beyond the standard information from the shipment. Standard information includes:ShippingCategory
is basically a wrapper for a string. One use is to code up specific rates, eg. "Fixed $20" or "Fixed $40", from which a calculator could extract imposed prices (and not go through its other calculations).Spree::Config[:shipping_instructions]
controls collection of additional shipping instructions. This is turned off (set to false
) by default. If an order has any shipping instructions attached, they will be shown in an order's shipment admin page and can also be edited at that stage. Observe that instructions are currently attached to the order and not to actual shipments.Spree Active Shipping
extension harnesses the active_shipping
gem to interface with carrier APIs such as USPS, Fedex and UPS, ultimately providing Spree-compatible calculators for the different delivery services of those carriers.spree-active-shipping
extension add the following to your Gemfile
:bundle install
from the command line.ShippingMethod
with a descriptive name (Configuration
-> Shipping Methods
) and a Calculator
(registered in the active_shipping
extension) that ties the delivery service and the shipping method together.spree_active_shipping
extension comes with several pre-configured calculators out of the box. For example, here are the ones provided for the USPS carrier:spree_active_shipping
gem needs some configuration variables set in order to consume the carrier web services.spree_active_shipping
extension can be easily added. Say, for example, you need First Class International Parcels via the US Postal Service.Calculator::Usps::Base
and implements a description class method:description
method must exactly match the name of the USPS delivery service. To determine the exact spelling of the delivery service, you'll need to examine what gets returned from the API:spree_active_shipping
gem returns an array of services with their corresponding prices, which the retrieve_rates
method converts into a hash. Below is what would get returned for an order with an international destination:compute
method selects the one that matches the description of the calculator. At this point, an optional flat handling fee (set via preferences) can be added:activate
method:available?
method returns true
by default. It is, therefore, the zone of the destination address that filters out the shipping methods in most cases. However, in some circumstances it may be necessary to filter out additional shipping methods.available?
method must be overridden as follows:create_proposed_shipments
on an Order
object while transitioning to the delivery
state during checkout. This process will first delete any existing shipments for an order and then determine the possible shipments available for that order.create_proposed_shipments
will initially call Spree::Stock::Coordinator.new(@order).packages
. This will return an array of packages. In order to determine which items belong in which package when they are being built, Spree uses an object called a Splitter
, described in more detail below.Spree::Stock::Coordinator
is the starting point for determining shipments when calling create_proposed_shipments
on an order. Its job is to go through each StockLocation
available and determine what can be shipped from that location.Spree::Stock::Coordinator
will ultimately return an array of packages which can then be easily converted into shipments for an order by calling to_shipment
on them.Spree::Stock::Packer
object is an important part of the create_proposed_shipments
process. Its job is to determine possible packages for a given StockLocation and order. It uses rules defined in classes known as Splitters
to determine what packages can be shipped from a StockLocation
.Spree::Stock::Splitter::Weight.threshold
(defaults to 150
) in an initializer.Spree::Stock::Splitter::Base
, you can create your own splitter.spree.rb
file:spree.rb
file:StockLocation
, you need to decorate the Spree::Stock::Coordinator
class and override the splitters
method.Spree::Stock::Prioritizer
object will decide which StockLocation
should ship which package from an order. The prioritizer will attempt to come up with the best shipping situation available to the user.Spree::Stock::Adjuster
is also used to ensure each package has the correct number of items.sort_packages
method in Spree::Stock::Prioritizer
.Adjuster
visits each package in an order and ensures the correct number of items are in each package. To customize this functionality, you need to do two things:adjust
method to get the desired functionality.Spree::Stock::Coordinator
and override the prioritize_packages
method, passing in your custom adjuster class to the Prioritizer
initializer. For example, if our adjuster was called Spree::Stock::CustomAdjuster
, we would do the following in app/my_store/spree/stock/coordinator_decorator.rb
:Spree::Stock::Estimator
loops through the packages created by the packer in order to calculate and attach shipping rates to them. This information is then returned to the user so they can select shipments for their order and complete the checkout process.