Shipping infrastructure and generic implementation (OCC-60)

[bleroy]

Shipping is a very complex feature set, that may not be necessary in the minimum feature set, but is vital to many if not most businesses.

1. The feature must allow for multiple shipping providers to be active and contribute at the same time.
2. Specific implementations may rely on external web services, and as such must be async and fault-tolerant.
3. Product dimensions (weight, volume, length, width, and height, as well as maybe a flag for unusual shapes) can be stored on a Dimensions part that can be added to products and that is not implementation-specific.

A generic implementation would likely be mostly manually operated, and would be a place to store external tracking links, shipping provider name, and simple pricing determination based on weight and volume intervals. It should not attempt to be too sophisticated, as that would likely imply specialization that should really live in provider-specialized extensions.

Note: there exist Stripe-like shipping broker services that could also be good first implementations or extensions to build.

Jira issue

[jeffolmstead]

I don't know about other countries, in the USA the notion of a "Size" picklist is very handy as a lot of clients set up their generic shipping pricing matrix based on "Size" and "Destination" (where "Destination" is either a state and/or country. This works pretty good because of flat rate boxes. So for the generic one I would love to see a toggle between "Size" based approach and "Unit" based approach.

[Skrypt]

Fixed rate and Rate by size/weight with excel spreadsheet import/export.

[MatteoPiovanelli-Laser]

Destination: I think resurrecting something like the Territories form Nwazet would be useful, to match shipping and taxes.

I think the generic shipping method should not have "size" or properties like that. We should, however, provide an extension point for those. Meaning that a shipping method would have its own list of those conditions

[bleroy]

Please open a separate issue for territories.

The reason for having size outside of providers is that they really are common. If I ship through FedEx and USPS, they will both require weight. I don't want to have to enter a USPS weight and a FedEx weight for the same product. Am I missing something?

This being said, we could have a weight part, a volume part, and so on.

[MatteoPiovanelli-Laser]

Specifically the weight: I see that as something attached to the product. Both USPS and FedEx providers would look for that on products in a checkout step where shipping is "computed".

A free or fixed price shipping would not need that.

[bleroy]

I think we're in violent agreement: if you don't use shipping methods that depend on dimensions, you don't have to have the part on your products. USPS and FedEx could still look for it though.

[Skrypt]

Destination: I think resurrecting something like the Territories form Nwazet would be useful, to match shipping and taxes.

Shipping providers usually returns prices with tax. So there is no need to tax again shipping rates. It's supposed to be added on top of the actual invoice total price + taxes :

(Multiple Product Prices) = (Invoice Subtotal + Tax) (Invoice Subtotal + Tax) + Shipping Price = Invoice Total

[MatteoPiovanelli-Laser]

you would still need to tax the other products in the cart, right? Or do shipping providers take care of that?

[Skrypt]

The shipping price is a separate product which includes it's own tax. If you use USPS they will include tax depending on where the package departs from. Though, the shipping tax is not part of the Invoice tax because it is a service that is not given by you but by the shipping provider. So you don't need to manage these tax in your accounting.

The shipping provider is a "subcontractor"

Though the tax provider is a feature that we require too.

[MatteoPiovanelli-Laser]

I understand now. But taxes on the products in the cart also depend at least in part on the destination of shipping. That is the match I meant.

[bleroy]

Some Nwazet implementation links for reference below. NWazet used the USPS shipping service, which may be a little dated, but gives a good reference point for what it takes to implement a shipping service for items that vary in size and weight, to any place in the world.

• https://github.com/bleroy/Nwazet.Commerce/blob/master/Services/IShippingAreaProvider.cs
• https://github.com/bleroy/Nwazet.Commerce/blob/master/Services/IShippingMethodProvider.cs
• https://github.com/bleroy/Nwazet.Commerce/blob/master/Services/ShippingService.cs
• https://github.com/bleroy/Nwazet.Commerce/blob/master/Services/UspsService.cs
• https://github.com/bleroy/Nwazet.Commerce/blob/master/Services/UspsContainer.cs
• https://github.com/bleroy/Nwazet.Commerce/blob/master/Services/UspsShippingMethodProvider.cs
• https://github.com/bleroy/Nwazet.Commerce/blob/master/Services/UspsWebService.cs
• https://github.com/bleroy/Nwazet.Commerce/blob/master/Services/WeightBasedShippingMethodProvider.cs
• https://github.com/bleroy/Nwazet.Commerce/blob/master/Services/SizeBasedShippingMethodProvider.cs
• https://github.com/bleroy/Nwazet.Commerce/blob/master/Models/UspsSettingsPart.cs
• https://github.com/bleroy/Nwazet.Commerce/blob/master/Models/UspsShippingMethodPart.cs
• https://github.com/bleroy/Nwazet.Commerce/blob/master/Models/UspsShippingOptionList.cs
• https://github.com/bleroy/Nwazet.Commerce/blob/master/Models/WeightBasedShippingMethodPart.cs
• https://github.com/bleroy/Nwazet.Commerce/blob/master/Models/SizeBasedShippingMethodPart.cs

[dpomt]

Is implementation of shipping (costs) is already in progress? I am currently porting an O1 website to OC.

In O1 Nwazet.Commerce there was an IShippingMethodProvider interface. Implement a custom shipping method just needs to derive from that interface.

For Orchard Commerce, I do not see any interfaces or preparations for handling shipping costs.

Since my shipping costs calculations depend on the ZIP, I would ask user for ZIP and store it together with the calculated shipping cost. But where to store them? Should ShoppingCartViewModel be extended to keep the info about shipment? I thought about implementing a new class deriving from ShoppingCartEventsBase and use this to calculate the shipping costs. Would that be a way to go? If not, any suggestions?

ShoppingCartViewModel

Thanks, Dieter

[sarahelsaig]

Hi Dieter,

this issue is not in progress. It's up for grabs to the community if anyone is interested.

I would ask user for ZIP and store it together with the calculated shipping cost. But where to store them?

I don't think storing the price is the best approach. If your shipping cost only depends on the shipping address, then it's more efficient to store a table that correlates ZIP to shipping price as an OC site setting or in appsettings.json and just look that up when needed.

You can already generate shipping cost as an additional cart item using current OrchardCore.Commerce like this:

In OCC if the user has a saved address (in ~/user/addresses) that's taken into consideration during the initial price calculation. Also when you change the shipping address fields during checkout, that too triggers order recalculation using the ~/checkout/price API. Under the hood, price calculation uses the same IPaymentService.CreateCheckoutViewModelAsync() that payment processing and order creation relies on as well. Internally that fetches the shopping cart and creates a model of it. At the end of the shopping cart model creation it invokes the IShoppingCartEvents.ViewModelCreatedAsync() event. So if you add your own IShoppingCartEvents implementation, you can use it to add an extra entry to viewModel.Lines representing the shipping costs, and increment viewModel.Totals[0] accordingly. You may have to update the ShoppingCartCell_Action.cshtml and ShoppingCartCell_Quantity.cshtml shapes to prevent interacting with this generated entry.

Hope this helps.

[dpomt]

Thanks Sára,

I am actually trying this and looks great.

Wenn adding an extra entry to viewModel.Lines it is necessary to also reference a Product content item, since otherwise code will not work in many places. To distinguish a shipping cost product from a normal product, what do you think about having a separate content type "ShippingCost" with a ProductPart and stereotype "ShippingCost". That would allow to make ShoppingCartCell_Action.cshtml, ShoppingCartCell_Quantity.cshtml etc. more generically.

Thanks

[dpomt]

Hi Sára,

when adding the shipping cost only to the viewModel.Lines as described before, it is not part of the created order :(

PaymentService.CreateOrUpdateOrderFromShoppingCartAsync calls via alterOrderAsync(order, isNew, total, cartViewModel, lineItems); e. g. CreateOrUpdateOrderFromShoppingCartAsync

but the implementation of CreateOrUpdateOrderFromShoppingCartAsync update the lines of the order part orderPart.LineItems.SetItems(lineItems); to the supplied lineItems, not to the lines of the view model.

Any suggestions?

[dpomt]

This could be fixed in Payment/Services/PaymentService.cs in methods CreatePendingOrderFromShoppingCartAsync and CreateOrUpdateOrderFromShoppingCartAsync:

Instead of _shoppingCartHelpers.CreateOrderLineItemsAsync(cart) call _shoppingCartHelpers.CreateOrderLineItemsAsyncEx(cartViewModel) (created CreateOrderLineItemsAsyncEx similar to existing CreateOrderLineItemsAsync but accepting the view model of the cart instead of the cart itself).

See also https://github.com/OrchardCMS/OrchardCore.Commerce/issues/397