Skip to content

Instantly share code, notes, and snippets.

@thenbrent
Created August 8, 2016 17:52
Show Gist options
  • Save thenbrent/26ba2035745667301fbd3b4cc6d13fc1 to your computer and use it in GitHub Desktop.
Save thenbrent/26ba2035745667301fbd3b4cc6d13fc1 to your computer and use it in GitHub Desktop.
Brief developer's guide to the application flow during the subscription renewal process within WooCommerce Subscriptions

WoCommerce Subscriptions processes automatic renewal payments via the following flow:

  1. its scheduling system, Action Scheduler, will run every minute and find any woocommerce_scheduled_subscription_payment actions scheduled to run now or within the last minute
  2. if there are woocommerce_scheduled_subscription_payment actions scheduled for anytime before now, Action Scheduler will grab a batch of those actions and begin processing them (which just means triggering do_action( 'scheduled_subscription_payment', $subscription_id ) for any 3rd party code to handle)
  3. Subscriptions attaches two important functions as callbacks on the 'woocommerce_scheduled_subscription_payment' hook to process renewal for that subscription when it is called:
    1. WC_Subscriptions_Manager::prepare_renewal(), which is responsible for creating a pending renewal order, putting the subscription on-hold etc. (this is attached with a priority of 1 to make sure it runs before any other logic).
    2. WC_Subscriptions_Payment_Gateways::gateway_scheduled_subscription_payment(), which checks if the subscription requires an automatic payment, and if it does, triggers a special gateway specific hook for gateway extensions, like Stripe, to use to process the automatic payment
  4. After a renewal payment is processed by the payment gateway, it should change the orders status by calling $order->payment_complete() (or in some rare cases, by manually updating the status order's status) which trigger's WooCommerce's 'woocommerce_order_status_changed' hook.
  5. Subscriptions attaches the WC_Subscriptions_Renewal_Order::maybe_record_subscription_payment() method to the 'woocommerce_order_status_changed' hook to monitor order status changes and process renewals as needed.
  6. When the 'woocommerce_order_status_changed' hook is triggered for a renewal order, and the new status is a payment complete status, like processing or completed, Subscriptions will loop over all the subscriptions associated with that renewal order (which is only ever one by default, but can be more than one with custom code) and will process the payment accordingly:
    1. in the case of successful payment, that means calling $subscription->payment_complete()
    2. in the case of failed payment, that means calling $subscription->payment_failed()
  7. Via those functions, Subcriptions will then leave an order note about the payment status and either reactivate the subscription or leave it on hold depending on payment status
  8. When the subscription is reactivated, the next payment date is calculated and scheduled starting the whole process over again (if there is a next payment date)
@sadiqodunsi
Copy link

Thanks for this explanation. On number 8, do you know how the next payment calculated and scheduled? Is there any hook available?

Been searching but can't find anything.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment