OrderCloud’s subscription feature

OrderCloud’s subscription feature basically consists of API’s to manage subscription data, and secondly triggering an integration call from OrderCloud when a Subscription is reaching the subscription data & time. As with anything else in a composable setup, you must handle “the rest” as in; Sending email/text notifications, placing the order etc. 
In the following I will show how I created a very simple minimal Next.js app to handle these subscription events, and a skeleton for performing the following tasks. 

Creating a default Next app

OrderCloud Subscription API

Now we have our default Next app running. Let’s look at the OrderCloud Subscription API.
In OrderCloud we need to define a call-back, telling OrderCloud where to send information on Subscription once a subscription order has been created (or if it failed), please also see here. This can be done using a call like this - from postman or directly on the OrderCloud portal:

You will obviously need to the correct access and role to be able to do that. 

Creating subscriptions in OrderCloud

Now we need to create some subscriptions, and then just “wait” for OrderCloud to call back. 
Basically, it’s a simple set of APIs to manage the Subscriptions in OrderCloud, but there’s some basic information on each Subscription that has to be there for it to work:

• Payment
• Billing address
• Shipping address

Below an example creating an subscription from Postman:

As you might notice, I have set the BillingAddressID and the ShippingAddressID to the same. That obviously would be a normal case for delivery orders, where as a pick-up-in-store might have the ShippingAddressID pointing the Store address. 

With a “Subscription” created above, we can now start adding subscription items:

"An hourly function that queries for active subscriptions, from an active user, with a NextOrderDate within the last five hours and an EndDate that is either null or in the future.
If the process to create the order, line items, and payment fails, it will keep trying until NextOrderDate is more than five hours ago."

Please also remember that datetime in OrderCloud is in UTC.

For testing I have used Postman, with some simple scripting so I don’t have to copy “subscriptionId” when I create the subscription items etc. 

ngrok

As you saw on the Integration Definition previously, I created a URL for OrderCloud to call back to. As I want to test this out locally, I use ngrok to provide that functionality (see: https://www.ngrok.com)
After installing ngrok, I open up another Terminal in my VS Code and type:

ngrok http http://localhost:3000

Which should show you something like this:

With this, OrderCloud can call back to the URL I provided as part of the Integration setup:

https://1dd6-108-5-123-41.ngrok-free.app/api/subscriptions

IMPORTANT: As you see we provided an URL that looks like…/api/subscriptions. This means that OrderCloud call back to either:
• …/api/subscriptions/success, or 
• …/api/subscriptions/failure

Performing tests

The most time-consuming thing working with Subscription features is testing. First of all you’ll have to make sure that you use the correct date time (UTC), secondly you have to wait for the Integration event from OrderCloud to trigger. But since the subscription feature was first released - some nice features has been added that help testing a lot. On the OrderCloud dashboard you can manually trigger the events! And that just saves as a lot of time:

Middleware Next app

At this point we only need to make sure our Next App exposes the defined endpoints for “success” and “failure”.  For that I have added a simple structured route that looks as follows: 

I have defined an interface for the incoming request from OrderCloud:

The request handler is kept as simple as possible:

There’s room for improvement for sure:

• Validating that the request actually comes from OrderCloud, using the OrderCloudAccessToken
• Only returned “HttpStatusCode: 200” if all actions works as expected. Returning 200 here will tell OrderCloud that it all worked fine, anything else will make OrderCloud retry on next subscription event until NextOrderDate is more than five hours ago.
• Sending notifications emails or text messages
  •  This goes for both notifications like “Hey Customer, your subscription order will be created in X days. If you need to do any modifications to your…… “
  • All other transaction messages for Order places, or could not be created as product X and Y was out of stock etc. There’s a lot of test cases to be handled. 

I have added this app to the following repository in case you want to look: https://github.com/alpharv/ordercloud-subscription-mw. There will be some updates/commits as other needed skeleton code get's added.  

Running the app and receiving requests from OrderCloud

On the ngrok console you will see something like this when a requests is received:

HTTP Requests
-------------

POST    /api/subscriptions/success   200  OK

On the app's console you'll see something like this:

This is a pretty nice feature as you can from ngrok then re-post/re-send the request to your app. A real time-saver as you then don't have to wait for the next requests from OrderCloud.

Note that at this time the Order has been created but it’s not yet submitted. We will get a similar request when the Subscription time is up – and that will still only say: "IsSubmitted": false. 
The middleware will now have to do the things that’s need for a normal order to submit:

• Calculate tax.
• Payment settlement with payment provider
• Shipment costs
• Send message and/or email with order is on its way message, potentially with tracking information
• Any other customizations needed such as handling out of stock issues etc. 

All these tasks would be something you already have in place if you have a running storefront.  

I hope this post was helpful if you’re establishing subscription feature for Sitecore OrderCloud. You’re more than welcome to reach with any questions or some comments.