Sitecore OrderCloud Documentation

docs

Portal login

Subscriptions

Published by Alexa Snyder on April 10, 2023

Last updated on August 31, 2023

In today's e-commerce market, subscriptions have become a popular business model for one simple reason: convenience. They enable a regular, predictable delivery of goods or services with little to no effort from the customer. Subscriptions also foster a greater brand loyalty from your customer base, providing more long term value.

The introduction of subscriptions in OrderCloud enables automated ordering for buyer users on a set interval and frequency for a predetermined or indefinite amount of time. This feature depends on the implementation of the subscription integration in order to submit orders, which is detailed below.

Use Cases

  • I sell consumable goods that my customers can either order on set schedule they define based on their needs or on an as needed basis

  • My product is a subscription based service/digital membership that I charge for monthly

  • My product is a collection of goods that are either standardized or customized for the user that are delivered on a set interval

Key Highlights

  • Set the interval and frequency on the subscription to determine how often the items are ordered -- A subscription will process once every {Frequency} {Interval}

  • Optionally add a reference to OrderCloud Payment information used for processing the subscription

  • Optional EndDate -- When null subscriptions will be processed indefinitely

  • There is no limit on how many subscriptions a buyer user can have

  • Seller users can create subscriptions on behalf of buyer users

  • Only products that are visible to the Subscription.FromUserID will be created as line items at the time the subscription order is created

  • New property on PriceBreak of SubscriptionPrice which allows you to set specific pricing for items processed via subscription

    • If an item on the subscription is being purchased is part of a bundle, the BundlePrice will always apply when it is defined. If it is not defined, then the following pricing precedence applies:

      • SubscriptionPrice

      • SalePrice

      • Price

  • New property on Order of SubscriptionID, which is a read only field identifying the subscription that the order was created for via hourly process

New Resource: Subscription

1"Subscription": {
2    "ID": "subscription1",
3    "Interval": "Days", // also accepts Weeks, or Months,
4    "Frequency": 1,
5    "NextOrderDate": "2022-11-19+00:00", 
6    "LastOrderDate": "2022-10-19T20:40:06.73+00:00", // read only
7    "EndDate": null, // optional
8    "FromCompanyID": "buyerCompany",
9    "FromUserID": "buyerUser",
10    "ToCompanyID": "sellerCompany",
11    "BillingAddressID": "billingAddress",
12    "ShippingAddressID": "shippingAddress",
13    "Payment": {
14        "Type": CreditCard, SpendingAccount, or PurchaseOrder 
15        "CreditCardID": "creditcardid", // optional
16        "SpendingAccountID": null, // optional
17    },
18    "xp": {}
19}

Endpoints: Writeable endpoints will require the SubscriptionAdmin role, while readable endpoints will require SubscriptionReader or SubscriptionAdmin. Currently only available to Admins and Buyers

  • GET v1/subscriptions

  • GET v1/subscriptions/{subscriptionID}

  • POST v1/subscriptions

  • PUT v1/subscriptions/{subscriptionID}

  • PATCH v1/subscriptions/{subscriptionID}

  • DELETE v1/subscriptions/{subscriptionID} Creating subscriptions for other buyer users will also require the OrderAdmin and UnsubmittedOrderReader roles.

Writeable endpoints will require the MeSubscriptionAdmin role, while readable endpoints will require MeSubscriptionReader or MeSubscriptionAdmin.

  • GET v1/me/subscriptions

  • GET v1/me/subscriptions/{subscriptionID}

  • POST v1/me/subscriptions

  • PUT v1/me/subscriptions/{subscriptionID}

  • PATCH v1/me/subscriptions/{subscriptionID}

  • DELETE v1/me/subscriptions/{subscriptionID}

Subscription Item

This data will be used to create a line item representing the subscription item when the subscription is processed.

1{
2    "ID": "shipmentItem1",
3    "ProductID": "product1",
4    "Quantity": 1,
5    "DateAdded": "2018-08-09T17:53:35.997+00:00",
6    "QuantityShipped": 0,
7    "UnitPrice": 15.00,
8    "PromotionDiscount": 0,
9    "LineTotal": 15.00,
10    "LineSubtotal": 15.00,
11    "CostCenter": null,
12    "DateNeeded": null,
13    "ShippingAccount": null,
14    "ShippingAddressID": null,
15    "ShipFromAddressID": null,
16    "Product": {},
17    "Variant": null,
18    "ShippingAddress": {},
19    "ShipFromAddress": null,
20    "SupplierID": null,
21    "InventoryRecordID": null,
22    "PriceScheduleID": null,
23    "PriceOverridden": false,
24    "Specs": [],
25    "xp": {}
26}

Endpoints: Writeable endpoints will require the SubscriptionAdmin role, while readable endpoints will require SubscriptionReader or SubscriptionAdmin.

  • 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}

Writeable endpoints will require the MeSubscriptionAdmin role, while readable endpoints will require MeSubscriptionReader or MeSubscriptionAdmin.

  • GET v1/me/subscriptions/{subscriptionID}/items

  • GET v1/me/subscriptions/{subscriptionID}/items/{subscriptionItemID}

  • POST v1/me/subscriptions/{subscriptionID}/items

  • PUT v1/me/subscriptions/{subscriptionID}/items/{subscriptionItemID}

  • PATCH v1/me/subscriptions/{subscriptionID}/items/{subscriptionItemID}

  • DELETE v1/me/subscriptions/{subscriptionID}/items/{subscriptionItemID}

New Resource: Subscription Integration

New OrderCloud resource required to process and submit subscription orders. Every hour, the OrderCloud platform will handle creating an order, line items, and payment for subscriptions due for processing at that time based on the subscription and subscription item data. This resource provides OrderCloud with the information needed to send relative data to a hosted application that will be responsible for checkout processes such as tax calculation, payment capture, and order submit.

Subscription Integration Key Highlights

  • One per marketplace

  • NotificationDays allows you to specify how many days before Subscription.NextOrderDate that a user is reminded via email their subscription order is coming up. This email is a new message sender that will need to be configured and assigned

  • Cannot use an API Client that is currently associated with the Order Checkout Integration Event -- Checkout is not driven by user interactions in a UI, therefore the Order Checkout Integration Event triggers would not work

  • API Client used must have a DefaultContextUser defined -- The platform will use the DefaultContextUser to generate an OrderCloud Access Token to send to the specified URL

1{
2	"ApiClientID": "", 
3	"HashKey": "",
4	"ElevatedRoles": [],
5	"Active": true,
6	"NotificationDays": 15,
7	"Url": "",
8	"xp": {},
9}

Endpoints: Requires SubscriptionAdmin role

  • GET v1/integrations/subscription

  • PUT v1/integrations/subscription

  • PATCH v1/integrations/subscription

  • DELETE v1/integrations/subscription

Because there is only one per marketplace, there is no ID associated with the Subscription Integration

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.

Payload to hosted application

1{
2    "Environment": "Sandbox",
3    "OrderCloudAccessToken": "", // access token of the DefaultContextUser defined with your associated API Client
4    "OrderWorksheet": {},
5    "UnavailableProductIDs": ["inactiveProduct"],
6    "ErrorCode": ""
7}

/success

If OrderCloud was able to successfully create an order, line items, and payment per the defined subscription and subscription items, the payload defined above will be sent to this endpoint in your hosted application. For example, if your SubscriptionIntegration.Url value is myhostedapp.com/api/subscriptions, OrderCloud will send the request to myhostedapp.com/api/subscriptions/success. Within this method, you will want to handle all your order submit logic such as payment capture, tax calculation, shipping designations, etc. You will also be responsible for submitting the order. If you currently utilize the Order Checkout Integration Event feature, you can call existing methods used for order checkout to do things such as calculate tax and capture payment.

/failure

If OrderCloud was unable to successfully create an order, line items, and payment per the defined subscription and subscription items, the payload defined above will be sent to this hosted endpoint in your application. For example, if your SubscriptionIntegration.Url value is myhostedapp.com/api/subscriptions, OrderCloud will send the request to myhostedapp.com/api/subscriptions/failure. Any custom error handling you want to happen would occur here.

Response to OrderCloud

1{ 
2    "HttpStatusCode": 200,
3    "UnhandledErrorBody": ""
4}

Both of the endpoints defined above will need to have a response type matching the object above. If HttpStatusCode is of a successful value and UnhandledErrorBody is null, the Subscription.NextOrderDate will be updated based off of the defined interval and frequency on the subscription. The response will be stored on the order worksheet as SubscriptionIntegrationResponse.

Subscription Reminder Message Sender

An hourly function that queries for active subscriptions, from an active user, with a NotificationDate within the next five hours and an EndDate that is either null or in the future. NotificationDate is a calculation of Subscription.NextOrderDate - SubscriptionIntegration.NotificationDays and is read only. If the message sender is assigned, the Subscription.FromUser will receive an email that their subscription order will be processed soon.

Subscriptions Self Service for Portal

As of August 31, 2023, there is now a mechanism for manually triggering subscriptions processing for your marketplace through OrderCloud Portal only. Self service subscriptions functions the same as the automated hourly process, which creates the associated order, line items, and payment data for any eligible and unprocessed subscriptions. This allows for greater control over the timing and frequency of the subscriptions processing job, primarily to aid in debugging during the development process. Manual subscription processing capabilities are limited to marketplace administrators only, with limits:

Environment

Hourly Job Limit

Sandbox

10

Staging

10

Production

3

Still have questions?
Ask in our Community Channel

Content Powered By
Sitecore Logo

© Copyright 2024, Sitecore OrderCloud®. All rights reserved.

Contact Us
Privacy Policy
Sitecore