Better Promotions Free Gift support

Is your feature request related to a problem? Please describe. It is quite common to have a promotion that entitles the customer to a free gift. Currently we are able to support making an item free using an PromotionItemAction, but the customer still has to manually add it to the order.

The ideal flow in this case however is that once the condition(s) pass, then Vendure can automatically add the free gift to the order.

To work around this, I have suggested in the past the creation of a custom addItemToOrder mutation which contains logic to achieve this. However, it would be better to support this common use-case natively.

Describe the solution you’d like Perhaps a new kind of PromotionAction which is dedicated to adding items the order. The exact mechanism of how this would actually work is not yet clear.

Currently all promotion actions are processed as part of the OrderCalculator.applyPriceAdjustments() method. I would not suggest using this same method to add a new item, since this is mixing concerns and also you get this recursive issue where adding a new item during the price calculation can then potentially trigger new promotions, potentially changing prices of those already added etc.

It would probably work in a separate stage, so:

1. Calculate order price including non-free gift promotion actions
2. Check for any free gifts to add
3. call OrderService.addItemToOrder() with any free gifts

Open questions

1. Do we want the free gift to be removed if the Promotion is no longer applicable? Or leave it in the order and just allow it to go to full price. The latter would be a much simpler implementation. With the former, we’d need to somehow mark the item as “auto added” and verify its status on every change to the order.
2. Do we want the free gift’s discount to be coupled to the act of adding it to the order? Or have it so it’s simply an “auto add” feature, and the “free” part is controlled in the present way with a PromotionItemAction.

[tianyingchun]

the flow very clearly: https://github.com/vendure-ecommerce/vendure/commit/1a4a117f6fca946dfa4999bad194c28c97f865eb

😃

[michaelbromley]

First feedback from testing:

• We need a way to handle errors that might arise in the side-effects. For example, I set up a free gift side-effect similar to the example above, but it wasn’t working. I found out it was because there was insufficient stock of the selected ProductVariant, so the orderService.addItemToOrder() call was returning an ErrorResult.

I think we can handle this by wrapping the calls to onActivate and onDeactivate in a try-catch, and in the case of an error, we convert that into a new type of ErrorResult which we’ll have to add to all the union types that can trigger a promotion side effect.