Move rate-related package concerns to a RateEstimate/Shipment model

[jonathankwok]

Discussion came up during #469, and a bit IRL:

Some concerns on the existing Package are not generic enough to be on the Package data model. For example, export reasons such as gift? or sale? are more intimately tied to the Shipment itself, which should be concerned with the actual shipment of a package from an origin to a destination with all the packages contained.

Similarly, information such as oversized? and dimensional_weight requires the knowledge of a carrier to determine - what constitutes oversized for UPS might not be oversized for USPS, for example. These can't live on the generic Package model.

I'm proposing a new model - a Shipment model, that represents the physical act of sending Package(s) from an origin to a destination with all the shipping options that may be included. Within a Shipment model will be one or more Packages, which each have a 1-1 relationship with a RateEstimate, since a RateEstimate is calculated by taking in the attributes of the Shipment as well as the Package.

Still a little amorphous in my head as to the exact implementation but just throwing these thoughts out there for discussion.

[RichardBlair]

Can you put together a small UML type diagram to model the relationships between these objects?

Additionally, we will want to nail down definition here. To me, I get a rate estimate for a package. It's not really a shipment yet, is it? Maybe it is? From http://www.dictionary.com/browse/shipment we can see a few definitions.

We should also sync on the direction we are going internally. It would be great if we were aligned, but if it doesn't make sense that is also okay (although less preferable)

[kevin-jj]

Thanks Shopify team for contributing this awesome gem.

Agree more with @jonathankwok. One shipment represents the delivery details containing several packages & origin/destination & shipping rates, but in my opinion one shipment should have many RateEstimate since one carrier has many service option such as 'Standard Shipping' and 'Express Shipping' etc.

@RichardBlair What you defined for RateEstimate is really a RATE CALCULATOR instead of entity-object relationship.

Thanks Shopify Team again. ActiveShipping Gem provides more insights for our team.

[jonathankwok]

@RichardBlair I've thought this out a bit more, didn't draw a diagram but I've tried to put it in the clearest way possible:

A Shipment has an origin (Location), a destination (Location), and one or more packages (Package).

A Package represents a single physical package. A Package has many PackageItems, which represent items within the package (and are only really relevant when making international shipments, for customs).

We then operate with the Shipment object to get rates/labels - for example, to fetch rates, we should be calling find_rates(shipment), rather than find_rates(origin, destination, packages, options). Similarly, to purchase a label, we'd call create_shipment(shipment), and not create_shipment(origin, destination, packages, options).

This also gives us the flexibility of inheriting from Shipment, e.g. CanadaPostShipment, or StampsShipment, which solves for us the problem of dimensional weight being determined per-carrier, or money parsing being different per API.

We'd also attach shipping options to a Shipment, since you cannot have shipping options on one package within a shipment without applying it to the others, and they feel like carrier-specific things. I'd need to look into this more though, to be sure.

[RichardBlair]

Do you buy a label for a shipment, or for a package? Or are you thinking about modeling this as 1 Shipment but multiple packages for carriers that support more than 1 package for a single label?

[jonathankwok]

The latter - you can possibly have multiple packages for a single shipment but they'll still have only one "label" (that can be used on multiple packages within the shipment, e.g. FedEx multipiece shipment.

So you'd purchase a label for a shipment.

[developingchris]

@jonathankwok I like where you are going with the idea of a Shipment.
If you ever read the shipping guidelines or any memos from the carriers, they refer to this concept as a Consignment. Which is everything on a single label, signature requirements, delivery guarantees, tariff codes, number of pieces on the label.
I think Shipment is a more humane way to name and explain it.