Let's Connect

Reach out to us for a discussion, a Demo or both!

This post shows one way, of many, how to establish a simple middleware to handle the Subscriptions feature that comes with Sitecore OrderCloud. 


Roland Villemoes

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

Doing a simple default "npx create-next-app@latest" and choosing all the defaults:

Console output from running a create next app command

Then adding the "npm install ordercloud-javascript-sdk --save" (from within the newly created "subscription-mw" folder:
Console output from adding ordercloud-javascript-sdk to a next js solution
With this, we have our plain simple default next app ready - "npm run dev":
screenshot showing a vanilla plain running next js app page.

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:


Screenshot showing example of posting a subscription specification to OrderClouds integration API

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:

Postman example of creating a subscription in Sitecore OrderCloud using the me/subscription endpoint

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:

Postman example of creating a subscription item in Sitecore OrderCloud using the me/subscription/items endpoint

Important note here on how the subscriptions will be triggered from OrderCloud:

"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. 



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:

screenshot showing output from ngrok console app just started up and ready to respond

Now anyone can call my localhost:3000 using this public URL, and please note that each time to stop ngrok and start it again, you will get a new public url (when you use the free version). 

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



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 


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:

Screenshot showing the Self Service Part of subscriptions on Sitecore OrderClouds portal


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: 

Screenshot showing default and simple app folder structure

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

Screenshot showing the interface definition for the SubscriptionRequest coming from Sitecore OrderCloud to our middleware application

The request handler is kept as simple as possible:

Example showing on how the Request from Sitecore OrderCloud can be handled in Next

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:

Screenshot from terminal console showing application output regarding sending notification regarding a subscription order

ngrok also give the option to show all requests and responses - in this case it would look like this:

Screenshot from ngrok logging showing first part of an incoming subscription request from Sitecore OrderCloud

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. 


OrderCloud Subscriptions

As part of API v1.0.276 a subscription feature was release for use with OrderCloud.

The API follows the same clean and easy-to-use pattern as all the existing APIs. To establish a fully functional subscription feature for your storefront(s), you need to do some work. OrderCloud takes care of all the usual stuff with persisting data, creating orders based on the subscription etc. You will have to handle the rest of the flow like payment settlement, communication with the customer and submitting the order. 

Sitecore OrderCloud – Subscriptions and the middleware