Understanding Auto Order Webhooks
- Jonathan Tew
- Hunter Schaeffer
Introduction
The purpose of this document is to explain how auto order webhooks operate. First let’s re-cap what an auto order is. An auto order is an object that handles repeat processing of items in a sequence. An auto order is created when a customer first purchases an item configured with an auto order schedule. That means there is a 1:1 relationship between an auto order and the original order that the customer purchased. Within the REST API this is referred to as the reference_order_id.
Webhook Overview
Next let’s cover the webhooks associated with auto orders and provide a brief description. The table below is going to show them in the order in which they can occur instead of alphabetized.
Webhook | Description |
|---|---|
auto_order_create | The create webhook is fired after the payment on the original order is processed successfully. At this point the auto order is activated. |
auto_order_update | The update webhook is fired whenever an update to the auto order record is performed within the UltraCart system. This can be caused by other REST API calls or users performing changes to the auto order. |
auto_order_rebill | The rebill webhook is fired whenever an auto order is successfully processed and generates a new order. |
auto_order_decline | The decline webhook is fired whenever UltraCart attempts to bill a customer on a new order and it’s fails. This webhook is your first indication that something is wrong with the customers order sequence. |
auto_order_cancel | The cancel webhook is fired whenever a customer is responsible for canceling the order. This can occur via 1) the easy cancel email link being clicked (if you have that feature enabled) 2) The customer interacting with the auto order cancel form you’ve placed on your website (if you have deployed that form) 3) A user clicking the cancel as customer button within the auto order editor. Typically they have called/emailed your customer service department and decided to cancel their subscription. |
auto_order_disable | The disable webhook is fired whenever an auto order is disabled instead of cancelled. This happens when the customers card has declined that maximum number of times or a user disables the order. |
The auto order object that your webhook receives will vary in complexity based upon the expansion string that you specify. The full list of expansion operations can be found on the Auto Order API documentation. You can expand out the original order as well as all the rebill orders when being notified about a change to an auto order via webhook. Having all of this information in a single webhook payload allows the developer to have a complete snapshot of the history associated with an auto order without making subsequent REST API calls to fetch information.
Example Sequence
Sequence | Webhooks Fired |
|---|---|
Order #1 <– Start subscription with an auto order | auto_order_create |
Order #2 (auto order) | auto_order_rebill + auto_order_update |
Order #3 (auto order) | auto_order_rebill + auto_order_update |
Order #4 (auto order) | auto_order_rebill + auto_order_update |
Attempt to charge for Order #5 failed. | auto_order_decline |
Order #5 (auto order) | auto_order_rebill + auto_order_update |
Customer contacts customer service. Customer service makes an adjustment to either the price or date of the next shipment | auto_order_update |
Order #6 (auto order)Â | auto_order_rebill + auto_order_update |
<Cancels subscription after Order #6> | auto_order_cancel |
You’ll notice that auto_order_update will fire in conjunction with other operations. This webhook is fired whenever the database record is updated. If you’re storing a copy of the auto order record off in your own database then listening to the auto_order_update operation is a good idea.
Related Documentation
https://www.ultracart.com/api/#resource_auto_order.html
Questions
If you have further questions about auto order webhooks and implementing your custom business logic using them, please contact support@ultracart.com and we will be glad to expand upon this documentation.