Incrementors

In modern e-commerce and enterprise systems, maintaining unique and organized IDs across various resources is crucial for efficient operations and seamless integration. The concept of incrementors within the OrderCloud platform provides a robust solution to manage sequential numbering for IDs effectively.

How do Incrementors Work?

Step 1: Create a new Incrementor.

1{
2  "ID": "",
3  "Name": "",
4  "LastNumber": 0,
5  "LeftPaddingCount": 0
6}

Key Fields:

• LastNumber - The last number that was generated, increments as IDs are generated

• LeftPaddingCount - Enforces a minimum length for the numbered part of an ID. If the number alone does not reach the minimum, then it will be padded with zeroes

Step 2: Reference the Incrementor When Creating a Resource

In the ID field of the new resource, reference the incrementor using {INCREMENTOR_ID}.

Example: Sequential numbering for orders

Let's say we need to add sequential numbering for our orders, a common requirement. Our objectives are:

1. Every order should start with the buyer company's name, TestCorp so that it can be differentiated easily by the supplier

2. The total number of characters for an ID must be a minimum of 20 characters long (ex: TestCorp-00000000001)

Incrementor Configuration

1{
2  "ID": "orderincrementor",
3  "Name": "Order Incrementor",
4  "LastNumber": 0,
5  "LeftPaddingCount": 11
6}

Creating an order with the incrementor:

1POST https://sandboxapi.ordercloud.io/v1/orders/all HTTP/1.1
2Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
3Content-Type: application/json; charset=UTF-8;
4
5{
6    "ID": "TestCorp-{orderincrementor}"
7}

1import { Tokens, Orders} from "ordercloud-javascript-sdk";
2
3Tokens.Set("INSERT_ACCESS_TOKEN_HERE")
4
5const order = Orders.Create('All', {
6    "ID": "TestCorp-{orderincrementor}"
7})
8.then(response => {
9    // returns the newly created order
10    console.log(response);
11})
12.catch(err => console.log(err));

1import { Tokens, Orders, Order, OrderCloudError } from "ordercloud-javascript-sdk";
2
3Tokens.Set("INSERT_ACCESS_TOKEN_HERE")
4
5const order: Order = await Orders.Create('All', {
6    "ID": "TestCorp-{orderincrementor}"
7})
8.catch((err:OrderCloudError) => console.log(err));
9console.log(order);

1using OrderCloud.SDK;
2
3var client = new OrderCloudClient(...);
4
5await client.AuthenticateAsync();
6
7Order response = await oc.Orders.CreateAsync(OrderDirection.All, new Order
8{
9    ID = "TestCorp-{orderincrementor}"
10});

This request will create an order with the ID TestCorp-00000000001

Best Practices & Considerations

Understand LeftPaddingCount: LeftPaddingCount represents the minimum number of characters for the numbering portion of an ID, not the maximum. For instance, if LeftPaddingCount is set to 1, the ID will increment as 1, 2, ..., 99, 100, 101, and so on. It's essential to ensure that downstream systems can handle IDs with varying lengths if they expect a fixed number of characters to prevent issues.

Unique Incrementors for Different Endpoints: It is recommended to use unique incrementors for each resource type (e.g., orders, products) to avoid sharing the sequence across different endpoints. Sharing a sequence can lead to undesirable consequences and data integrity issues.

Handle Asynchronous API Calls Carefully: Proper management of asynchronous API calls is crucial to prevent accidental duplicate ID generation. If you're not careful about how you handle your asynchronous API calls you may accidentally run into 409 ID conflicts, so be hygienic with your async calls.

Avoid Resetting LastNumber Property: Refrain from resetting the LastNumber property of an incrementor, doing so will result in 409 ID conflicts.

Sequential Submitted Orders
To ensure your submitted orders have sequential IDs, it's best to patch the ID with the incrementor after the order has been submitted. This approach prevents gaps between incremented orders, which can occur if unsubmitted orders, subject to cleanup rules, get deleted. By applying the incrementor post-submission, you maintain a consistent and continuous sequence of order IDs.

Conclusion

By leveraging incrementors effectively, businesses can streamline their ID management processes, enhance system reliability, and facilitate seamless integration with external systems like ERPs. This approach not only improves operational efficiency but also enhances the overall user experience by ensuring clear and consistent identification of resources throughout the application lifecycle.

Still have questions?
Ask in our Community Channel

Content Powered By