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
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).
Shipping Categories) and then assigned to products (
Shipmentobjects 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.
LineItemobjects 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:
ShippingCategoryis 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 Shippingextension harnesses the
active_shippinggem 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-shippingextension add the following to your
bundle installfrom the command line.
ShippingMethodwith a descriptive name (
Shipping Methods) and a
Calculator(registered in the
active_shippingextension) that ties the delivery service and the shipping method together.
spree_active_shippingextension comes with several pre-configured calculators out of the box. For example, here are the ones provided for the USPS carrier:
spree_active_shippinggem needs some configuration variables set in order to consume the carrier web services.
spree_active_shippingextension can be easily added. Say, for example, you need First Class International Parcels via the US Postal Service.
Calculator::Usps::Baseand implements a description class method:
descriptionmethod 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_shippinggem returns an array of services with their corresponding prices, which the
retrieve_ratesmethod converts into a hash. Below is what would get returned for an order with an international destination:
computemethod selects the one that matches the description of the calculator. At this point, an optional flat handling fee (set via preferences) can be added:
trueby 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:
Orderobject while transitioning to the
deliverystate 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_shipmentswill 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::Coordinatoris the starting point for determining shipments when calling
create_proposed_shipmentson an order. Its job is to go through each
StockLocationavailable and determine what can be shipped from that location.
Spree::Stock::Coordinatorwill ultimately return an array of packages which can then be easily converted into shipments for an order by calling
Spree::Stock::Packerobject is an important part of the
create_proposed_shipmentsprocess. Its job is to determine possible packages for a given StockLocation and order. It uses rules defined in classes known as
Splittersto determine what packages can be shipped from a
150) in an initializer.
Spree::Stock::Splitter::Base, you can create your own splitter.
StockLocation, you need to decorate the
Spree::Stock::Coordinatorclass and override the
Spree::Stock::Prioritizerobject will decide which
StockLocationshould ship which package from an order. The prioritizer will attempt to come up with the best shipping situation available to the user.
Spree::Stock::Adjusteris also used to ensure each package has the correct number of items.
Adjustervisits 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:
Spree::Stock::Coordinatorand override the
prioritize_packagesmethod, passing in your custom adjuster class to the
Prioritizerinitializer. For example, if our adjuster was called
Spree::Stock::CustomAdjuster, we would do the following in
Spree::Stock::Estimatorloops 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.