Sitecore
sitecore-ordercloud
Technical
Kautilya Prasad
VP, Sitecore Commerce and National Competency Lead
Fundamentals of Subscription Processing in Sitecore Order Cloud
Introduction
With the Subscription Box Industry booming, it is even more crucial for companies to leverage their eCommerce solution and claim their share of this $8.6 billion dollar industry. While the additional constant revenue source is appealing to companies, it is important to be relevant in the minds of consumers and deliver an engaging customer experience across channels they want to be reached in.
How are subscriptions stored?
Subscriptions are entities in the OrderCloud ecosystem just like orders, carts, etc. You can create a subscription entity by calling the POST /subscriptions API which has mandatory fields such as Frequency, Interval, and Next Order Date.
How can you trigger a subscription processing manually?
Once the subscription entity is created and items are added to the subscription, you can trigger a subscription job that looks at all the pending subscriptions in the system and creates a worksheet to post on the checkout integration process. It creates the associated order, line items, and payment data for any eligible and unprocessed subscription, primarily to aid in debugging during the development process.
Manual subscription processing capabilities are limited to marketplace administrators only. In STG and Sandbox, you can trigger up to 10 subscription processes manually per hour. The limit changes to 3 on PROD, which makes sense since this is primarily for debugging purposes.
What is an Automated Hourly Process?
In a real-world scenario, the order creation must happen automatically based on the subscription frequency and interval. Sitecore OrderCloud has an automated process of triggering this process that runs every hour. Once the order has been constructed from the subscription entity, it will be posted to the hosted application to run through the tax, payment, and other calculations. The below diagram will help you understand the automated hourly process.
What APIs are available to manage subscription entities?
- GET v1/subscriptions/{subscriptionID}/items
- GET v1/subscriptions/{subscriptionID}/items/{subscriptionItemID}
- POST v1/subscriptions/{subscriptionID}/items
- PUT v1/subscriptions/{subscriptionID}/items/{subscriptionItemID}
- PATCH v1/subscriptions/{subscriptionID}/items/{subscriptionItemID}
- DELETE v1/subscriptions/{subscriptionID}/items/{subscriptionItemID}
These APIs can be used to manage a subscription entity, allowing the user to add new products, remove products, add payment, and shipping to the subscription entity.
Can users be reminded of an upcoming subscription?
Looking at the diagram mentioned above, there is a notification date property. When the automated hourly job runs, it queries the system and if the subscription is not due today and the notification date is set to today, it will send an email to the customer using the integration event configured.
How does a sample subscription header entity look like?
{
"ID": "c_sgyAkl1kuvN9bhnD50Lg",
"Frequency": 365,
"Interval": "Days",
"NextOrderDate": "2024-07-18T17:36:57.107+00:00",
"LastOrderDate": null,
"NotificationDate": "2024-07-17T17:36:57.107+00:00",
"EndDate": null,
"Active": true,
"FromCompanyID": "Default_XC_Headstart_Buyer",
"FromUserID": "Vm-fIm4kcE2kvxWK5NSciw",
"ToCompanyID": "amit-marketplace",
"Payment": null,
"BillingAddressID": null,
"ShippingAddressID": "55ZQ309OW0iYwhzCgkKstg",
"xp": null
}
Sample Subscription Entity Detail
(https://sandboxapi.ordercloud.io/v1/subscriptions/{SubscriptionId}/items)
{
"Meta": {
"Page": 1,
"PageSize": 20,
"TotalCount": 1,
"TotalPages": 1,
"ItemRange": [
1,
1
],
"NextPageKey": null
},
"Items": [
{
"ID": "hH-09FJwd0C5O8Xc0TKO_Q",
"ProductID": "6042072",
"Quantity": 1,
"DateAdded": "2023-07-19T17:36:57.657+00:00",
"QuantityShipped": 0,
"UnitPrice": 180,
"PromotionDiscount": 0,
"LineTotal": 180,
"LineSubtotal": 180,
"CostCenter": null,
"DateNeeded": null,
"ShippingAccount": null,
"ShippingAddressID": "55ZQ309OW0iYwhzCgkKstg",
"ShipFromAddressID": null,
"Product": {
"ID": "6042072",
"Name": "2.1-Channel Soundbar System with Wireless Subwoofer",
"Description": null,
"Returnable": false,
"QuantityMultiplier": 1,
"ShipWeight": null,
"ShipHeight": null,
"ShipWidth": null,
"ShipLength": null,
"DefaultSupplierID": null,
"ParentID": null,
"xp": {
"IsSubscriptionProduct": true,
"SubscriptionOptions": [
{
"DisplayName": "Daily",
"Value": 1
},
{
"DisplayName": "Weekly",
"Value": 7
},
{
"DisplayName": "Monthly",
"Value": 30
},
{
"DisplayName": "Yearly",
"Value": 365
}
],
"Status": "Draft",
"Currency": "USD",
"ParentCatalogList": "59ddadc1-9b88-727e-9e14-3f6cf321ae0f",
"ParentCategoryList": "a0860c27-2a32-841f-7014-75b163b9471e|9ade273a-6370-e6f3-e593-cd215301f108",
"Images": [
{
"updated_at": "0001-01-01T00:00:00-06:00",
"ThumbnailUrl": "https://accelerator-qa.xcentium.net/-/media/83b777e08fe54983af2916aaadd11f7f",
"product_id": 6042072,
"admin_graphql_api_id": null,
"alt": null,
"width": 0,
"created_at": "0001-01-01T00:00:00-06:00",
"variant_ids": null,
"id": "Entity-SellableItem-6042072",
"position": 0,
"url": "https://accelerator-qa.xcentium.net/-/media/83b777e08fe54983af2916aaadd11f7f",
"height": 0
}
],
"Brand": "SoundArt",
"Category": "Soundbars",
"Price": "$100 - $200",
"PriceRange": "",
"Value": "",
"PriceValue": "",
"Attribute": "",
"Range": "",
"Details": {
"About": "<li>80W total output power: Provides dynamic sound.</li><li>Wireless subwoofer: For deep, powerful bass.</li><li>Bluetooth music streaming Makes it easy to enjoy tracks stored on a compatible Bluetooth-enabled device (not included).</li><li>Sleek appearance: Fits seamlessly along most HDTVs for a streamlined look.</li><li>Inputs: Include RCA x 2, optical digital audio and mini jack; Remote control: Enables simple operation from a distance.</li>"
},
"Tax": {
"Category": "Test",
"Code": "Headstart Tax Code",
"Description": "Mock Tax Code for Headstart"
}
}
},
"Variant": null,
"ShippingAddress": {
"ID": "55ZQ309OW0iYwhzCgkKstg",
"DateCreated": "2021-09-03T20:39:21.443+00:00",
"CompanyName": null,
"FirstName": "Default",
"LastName": "Buyer",
"Street1": "110 5th St",
"Street2": null,
"City": "Minneaplis",
"State": "Minnesota",
"Zip": "55403",
"Country": "US",
"Phone": null,
"AddressName": null,
"xp": null
},
"ShipFromAddress": null,
"SupplierID": null,
"InventoryRecordID": null,
"PriceScheduleID": "6042072-Guest",
"PriceOverridden": true,
"Specs": [],
"xp": {
"IsSubscription": true,
"SubscriptionValue": {
"DisplayName": "Yearly",
"Value": 365
}
}
}
]
}
Subscriptions are becoming very important for commerce businesses. If you’re interested in learning more and how they can be launched as part of your commerce experience and strategy, reach out to us at info@xcentium.com