Expiring or Termed Subscriptions Using Webhooks

Updated March 18, 2023 21:29

Creating this experience will require work from the client's development team or their technology partners and is expected to be self-serve.

If the client requires technical support from the Ordergroove team then any hours used will be applied toward the available service hours within the client's agreement. If not enough service hours are available then you may purchase additional hours by contacting Ordergroove.

Additionally, if you'd like to discuss possible customizations to this experience as outlined below please contact Ordergroove for a consultation.

Overview

Synopsis	Expiring subscriptions are subscriptions that are canceled after a set of conditions are met. The most common reason clients build expiring subscription functionality is to power a subscription that will cancel after a defined number of shipments. In order to set this up, you'll need to create a custom application that can receive HTTPS requests from our platform and configure your Ordergroove program to send webhooks to that application.
Areas Impacted	Front end for tracking which items are termed subscriptions on the order Backend for handling cancel logic when subscription should expire Backend for receiving webhook data
Out of Scope of Solution	Order XML modifications Different endpoint for termed subscription and standard subscription orders Custom messaging (current order count, remaining orders, etc.) in Ordergroove transactional emails Display of current or remaining order counts in Ordergroove Subscriptions created via Instant Upsell Subscriptions created via Ordergroove Gift subscriptions managed by a different user other than the individual creating the subscription
Requirements	Webhooks Integration Cancel Application
Resources Required	Client/Systems Integrator [S-M] Create separate SKUs for termed subscriptions [M] Create an endpoint to receive data from OG webhooks [S] Configure webhook setup [L] Create a cancel application that: Ingests the webhook data for a subscription determines when a subscription should be canceled Make an API call to cancel the subscription when the criteria are met

Caution!

You should instruct your Customer Service Representatives that termed subscriptions should not be created via your Ordergroove admin. Doing so could result in the subscriptions never getting canceled through your cancelation application.

Example Design Using Subscription Extra Data

You’ll want to set up a listener endpoint for Ordergroove’s subscription creation webhook.

NOTE:

If using Shopify as your eCommerce platform, you will already see that there are webhooks created for our communication with Shopify. Please make sure not to update or disrupt those existing webhook settings, but instead create new ones.

When the subscription webhook triggers to you and contains a termed SKU - you’ll want to call the Subscription Update endpoint and pass in extra_data information that will set the fulfillment counter (you can choose any key/value pair for this, but for this documentation, we’ll use “fulfillment_counter” and a string as the number “2”).

For example, this is what you could send in the body of the PATCH to update:

"extra_data":{
  "fulfillment_counter": "2",
  "termed": "true"
}

By including the termed true setting, there will be an identifier returned to the front end to assist you with visuals in the Subscriber Dashboard via the Ordergroove Code Editor.

When a recurring order is placed successfully for a gift, you will call Ordergroove’s REST endpoint to update the fulfillment_counter again.

For any eCommerce environment, Ordergroove can send a webhook notification when an order is successful.
For Shopify merchants, Ordergroove can set subscription ID, counter, and original order ID as line item properties on the order.

NOTE:

Updating subscription extra_data will overwrite the existing values of everything in that field, so be sure to copy and update all information to patch back to the endpoint

When a customer has reached their last order, you will make a call to update subscription extra data with an addition of “hide”: true so that you can hide this from reactivation, and then you will also call the cancel subscription endpoint to cancel.

Example of What The Data Flow Could Look Like