Custom Order Number in Sitecore OrderCloud

Introduction

In this article, we will discuss the importance of assigning a custom order number to an order and how we can achieve that in Sitecore OrderCloud. First, the order number is the crucial piece of identification information that customers will obtain after each successful checkout. The buyer and seller can access the order number used to track the order and can use it to support team for checking the order status, cancelling it, or making any changes. When it comes to integrating any payment gateway or fulfillment service provider, they expect a unique reference number for each order which also tracks the order payment or fulfillment status.

Why custom order number?

OrderCloud is a great platform for building large-scale eCommerce solutions. The platform focuses on the general need for order identification by assigning a random number consisting of alphabets and numbers which can be 100 characters long. A sample order number from OrderCloud looks something like “uvfFh1OZD0yXTqaMnk9r2g” which serves the purpose of having a unique order number, but makes it harder to remember and share with buyers or sellers during order updates.

Solution

Together we'll explore the best way to assign custom order numbers for OrderCloud orders. Before we jump in to the solution for custom order numbers, we should understand incrementors that are used to apply an auto-incremented number to any object ID.

Incrementors can be created using create incrementor API by providing the last number and left padding count.

Once you have created an incrementor, you can use that to assign the custom order number.

The next step is to define a prefix of the order number which could be 2-4 characters long. It has handy to have a prefix:

• To represent the company in order numbers using the company's initials
• When there are multiple stores setup using one marketplace
• When there are multiple types of orders from single stores e.g a regular order or subscription

Before authorizing the payment, the custom order number should be assigned using the Order update API for partially updating an order. Assuming you have created your incrementor using ID “orderIncrementor” and your prefix is “NAC” which is either coming from a config or generated by custom logic.

API should be called using the existing order number, set the value for field “ID” to “NAC{orderIncrementor} and submit.

Below is the reference for using OrderCloud portal to partially update orders for having a new ID.

When an order is re-submitted due to any issues in the initial payment, custom orders should not be re-generated. So, the payment will be made against the same order.