Updating the purchase status of wishlist items

A key aspect of how the plugin works particularly when used as a gift registry is in marking wishlist items as purchased.

Firstly, the purchased quantity column on the wishlist items table has to be visible for the plugin to tell that the administrator wants purchases to be registered for the wishlist items.

Purchased quantity column on the wishlist items table
Purchased quantity column on the wishlist items table

Secondly, item purchases are only registered after the order has been paid for. This means that after an order containing a wishlist item has been created at checkout, the wishlist item purchase status would still be zero until the order has been set as paid in the WooCommerce order page in the WordPress backend. This is typically when the status of the order is updated to processing or completed.

Once the order has been paid for, the plugin would start tracking the quantity of the wishlist item in the order, updating it when necessary such as when the order status changes or there is a refund.

The plugin updates the purchased quantity of the wishlist item only at specific order statuses which correspond to the item being purchased or refunded. The status of the order must be in, or updated to, any of these statuses for the wishlist item purchased quantity to be updated. (Table 1 below shows these statuses). Changing the item quantity during a manual refund, or deleting the manual refund, are two actions which would also result in the item purchased quantity being updated regardless of the order status as long as it is not a payment cancelled status. (Table 2 below shows these actions).

The third and final thing to know about how purchases are recorded is that the plugin only tracks the quantity of the wishlist item present in the paid order. It does not track the price paid for the item or any other detail about it. This means that the price may change for example, or be set to zero, as is the case when the order is fully refunded, but as long as there is a valid quantity for the wishlist item in the order, say one, this would still be recorded as a purchase.

Essentially, wishlist item purchased quantities are tracked in a similar way to how WooCommerce tracks the stock levels of products in the order. So generally, if the stock level of a product (for products which have managed stock) which is also a wishlist item reduces in the order, the wishlist item is marked as purchased and its purchased quantity is increased. If the stock level increases, the wishlist item’s purchased quantity decreases and the action is treated as a refund of the reduced quantity of the wishlist item. It doesn’t mean that wishlist items are tracked with the stock levels of products. They are tracked independently by the plugin and their tracking manner can be modified using action and filter hooks. However the tracking manner works similar to how WooCommerce tracks product stock levels in an order depending on the change in order status or the execution of other actions on the order screen.

Table 1: Order statuses that trigger an update of the wishist item purchased quantity.

Order statusWishlist item purchased quantityAction
ProcessingSet to purchased or refundedItem purchased quantity for the order is increased or reduced. Refund action is triggered if quantity is reduced.
CompletedSet to purchased or refundedItem purchased quantity for the order is increased or reduced. Refund action is triggered if quantity is reduced.
CancelledSet to refundedItem purchased quantity for the order is reset to zero. Refund action is triggered.
PendingSet to refundedItem purchased quantity for the order is reset to zero. Refund action is triggered.

Table 2: Order actions that trigger an update of the wishist item purchased quantity.

Order actionWishlist item purchased quantityAction
Order manually refundedSet to refundedItem purchased quantity for the order is reduced. Refund action is triggered.
Manual refund deletedSet to purchasedItem purchased quantity for the order is increased.

Refunds

Once a wishlist item has been recorded as purchased, any reduction in its purchased quantity is regarded as a refund by the plugin and this may trigger refund emails to be sent to the wishlist owner if applicable. A refund of the price of the wishlist item in the order would not be recorded as a refund of the wishlist item because its purchased quantity is still the same in the order. To register refunds of wishlist items, their quantities in the order must be directly or indirectly reduced. Only downward changes to a wishlist item’s quantity in an order are treated as refunds by the plugin.

Item quantity must be reduced to register refunds.
Item quantity must be reduced to register refunds.

Usage Examples

As mentioned before, many of the actions on the order screen that update the product stock quantity also result in updating the wishlist item purchased quantity. However here are a few examples of how the wishlist item purchased quantity can be updated after the order has been paid for.

1. To update the purchased quantity of a wishlist item in an order:

  • Change the order status to on-hold to enable the order to be editable.
  • Update the quantity of the wishlist item in the order.
  • Change the order status to a paid status (typically processing or completed) to register the new wishlist item purchased quantity.

2. To reset the purchased quantity of a wishlist item in a particular order to zero:

  • change the order status to pending payment or cancelled or manually refund the wishlist item fully by setting its quantity to zero.

3. To manually refund a wishlist item in an order:

  • Make sure the order does not have a cancelled status (typically cancelled or pending).
  • Click the refund button below the items table on the order screen to make the wishlist item row editable.
  • Set the quantity of the wishlist item you want to refund in the ‘Qty’ column of the items table.
  • Save the refund.

4. To cancel a wishlist item refund:

  • Hover over the specific refund row on the items table to bring up the delete button.
  • Delete the refund.