How does removeShipmentFromWave API work

Answer

As per API javadocs :
The removeShipmentFromWave API removes each shipment line for the passed shipment from waves they have been included into.
Shipments may be removed from waves on an exception basis to postpone picking for a shipment due to circumstances such as:
-Change in Requested Ship Date/Delivery date of the shipment
-Cancellation of Pickup appointment date by the carrier

Additionally you will notice that this API will work even when Shipments have already been picked.

Consider a scenario where after picking and moving the inventory to the Pack Location, users realize the items are damaged.
In such a scenario, removeShipmentFromWave API call will only remove shipment from wave,the inventory that is already picked will not be moved back to the source pick location.
Here we suggest that customization be put in place to achieve any movement of inventory and instead of using removeShipmentFromWave use changeShipment API to remove the quantity from the shipment line and create new shipment for the quantity