Understand Points Lifecycle on Order Status Changes

Order status changes are the main trigger for purchase points, deduction of previously earned points, and return of used points. Understanding the lifecycle helps you choose statuses safely and diagnose unexpected balances.

Purchase Points

• Purchase points are awarded when an order changes into one of the selected Earning status values.
• The plugin stores _points_awarded on the order after awarding points.
• The award flow uses a lock marker to reduce duplicate processing during repeated status changes.
• Guest orders do not earn purchase points because there is no customer account to credit.
• Child orders and subscription resubscribe or switch orders are skipped by default.

Deducted Purchase Points

• If the order later changes into a selected Deduction status, the plugin can deduct the points previously awarded for that order.
• Deduction only runs when the order already has _points_awarded.
• The plugin stores _points_deducted after deduction to avoid repeating the same deduction.
• Common deduction statuses are cancelled, refunded, or failed, depending on your store policy.

Used Points And Returned Points

• Cart discount redemption stores used points on the order as _used_points.
• When an order becomes cancelled, refunded, or failed, the plugin can return those used points to the customer.
• Returned points are tracked with _yowcl_points_returned so the return does not repeat.
• Redeem-product points are deducted during checkout order processing and logged as points_redeem_product.

Referral Rewards

• Referral rewards are evaluated when an order reaches completed status.
• Referral coupon attribution takes priority over referral link attribution when the order used a referral coupon.
• Referral link rewards require a registered purchaser and a valid different referrer.
• Order-level markers prevent the same referral reward from being awarded twice.

Recommended Status Setup

1. Use a final or near-final paid status, such as completed, for earning points when your fulfillment process allows it.
2. Use cancelled, refunded, or failed as deduction statuses only if points from those orders should be removed.
3. Do not include the same unstable status in both earning and deduction logic unless you have tested the full order flow.
4. Place test orders that move through pending, processing, completed, cancelled, refunded, and failed statuses.
5. Check the order points summary after each status change.

Developer Override

Developers can use the yowcl_skip_points_for_order filter to skip point awarding for custom order sources, subscription cases, marketplace orders, or other business rules.