Subscriptions
This guide connects WooCommerce Subscriptions to KEYZY via webhooks, so licenses are created and updated automatically as subscriptions renew.
Prerequisites
This integration requires the WooCommerce Subscriptions plugin to be installed and active on your WooCommerce store. WooCommerce Subscriptions is a paid plugin by Woo that adds subscription functionality, including the “Subscription Created” and “Subscription Updated” webhook topics used in this guide.
Without WooCommerce Subscriptions, these webhook topics will not be available in your WooCommerce settings.
Set WooCommerce Settings
We can create two webhooks for now. One webhook is for creating and another one is for updating.
The first one is “subscription created”. The “subscription created” is called when your customer starts a successful subscription. The second one is “subscription updated”. The “subscription updated” topic is called whenever the subscription’s status changes: renewed, suspended, cancelled and so on.
First, go to WooCommerce Settings —> Advanced —> Webhooks
Click to “Add webhook” button for Subscription Created Topic
Subscription Created Topic Parameters
- Name: any name you like (e.g. “keyzy-subscription-create”)
- Status: Active
- Topic: Subscription Created
- Delivery URL:
https://api.keyzy.io/v2/webhooks/woocommerce-subscription - Secret: Please follow “Create a New Appkey Pair for Secret” section
- API Version: WP REST API Integration v1
Now, we’ve just created our first webhook for the “subscription created” topic. We need to create another one for “subscription updated”. To do that, click to “Add webhook” button again for the “subscription updated” topic.
Subscription Updated Topic Parameters
- Name: any name you like (e.g. “keyzy-subscription-update”)
- Status: Active
- Topic: Subscription Updated
- Delivery URL:
https://api.keyzy.io/v2/webhooks/woocommerce-subscription - Secret: Please follow “Create a New Appkey Pair for Secret” section
- API Version: WP REST API Integration v1
Create a New Appkey Pair for Secret
- Create a new appkey pair on https://app.keyzy.io/app-keys
- The label should be your base e-commerce base name (e.g.
https://www.your-domain.com/) - Permission: Write
- Is App Key Active?: True
- Copy only API KEY info to WooCommerce’s Secret field
- You only need one API KEY for all webhooks. Create one appkey pair and use the API KEY value for all webhooks.
What Happens to the License
| Subscription status in WooCommerce | What KEYZY does |
|---|---|
| Created | Creates the license. Its end date is the next payment date plus 5 days |
| Active (renewed or reactivated) | Extends the end date to the next payment date plus 5 days |
| On hold, Pending cancellation, Expired | Nothing. The license stays, and stops working after its end date |
| Cancelled, Trash | Deletes the license and its activations immediately. This cannot be undone |
The extra 5 days give a late renewal payment time to arrive before the license stops working.
A cancelled subscription cannot come back. WooCommerce does not allow a cancelled subscription to be reactivated. If the customer uses “Resubscribe”, WooCommerce creates a new subscription, and KEYZY creates a new license for it with a new serial number. The customer activates once more.
Pending cancellation ends in deletion. When the paid period ends, WooCommerce turns the subscription into “Cancelled”, and the license is deleted then.
Bear In Mind
- The product’s SKU number (in WooCommerce, it’s just SKU) and KEYZY’s SKU number should be the same
- Be aware that you need to create a subscription product on WooCommerce.
Troubleshooting
Empty webhook payload
If your webhooks are firing but KEYZY is not receiving any data, the webhook payload body is likely empty. This is a known issue when High-Performance Order Storage (HPOS) is enabled in WooCommerce.
Fix: Go to WooCommerce → Settings → Advanced → Features and enable High-Performance Order Storage compatibility mode. This ensures that subscription webhook payloads are populated correctly.
General tips
- Make sure that the webhook is active or not, if it gets errors, WooCommerce can turn the webhook automatically off.
- There is a lag between the order time and the webhook trigger time. You need to wait for a short time to see the subscription information on KEYZY dashboard.
How to debug
You may need to look at the responses from KEYZY service. To do that, please look at the logs under WooCommerce —> Status —> Logs. You’ll see files starting with webhooks-delivery-YYYY-MM-DD--UNIQUE-ID (e.g. webhooks-delivery-2021-12-05-cf5ea08f2e6045ad6d889249b3ef8fa3.log)