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.

Core concepts

Incrementor model:

{  
  "ID": "",
  "Name": "",
  "LastNumber": 0,
  "LeftPaddingCount": 0
}

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

Implementation

1. Create incrementor
2. Reference in resource ID: {INCREMENTOR_ID}

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

• Every order should start with the buyer company's name, TestCorp so that it can be differentiated easily by the supplier
• The total number of characters for an ID must be a minimum of 20 characters long (ex: TestCorp-00000000001)

Configuration:

{
  "ID": "orderincrementor",
  "Name": "Order Incrementor",
  "LastNumber": 0,
  "LeftPaddingCount": 11
}

Implementation examples:

HTTP

POST https://sandboxapi.ordercloud.io/v1/orders/all HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8;

{  
    "ID": "TestCorp-{orderincrementor}"
}

JavaScript

import { Tokens, Orders} from "ordercloud-javascript-sdk";
Tokens.Set("INSERT_ACCESS_TOKEN_HERE")
const order = Orders.Create('All', {
  "ID": "TestCorp-{orderincrementor}"
})
.then(response => {
  console.log(response);
})
.catch(err => console.log(err));

TypeScript

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

C#

using OrderCloud.SDK;
var client = new OrderCloudClient(...);
await client.AuthenticateAsync();
Order response = await oc.Orders.CreateAsync(OrderDirection.All, new Order
{
  ID = "TestCorp-{orderincrementor}"
}

Result: Creates order ID TestCorp-00000000001

Best practices

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.

Related reading

• Using Extended Properties in Custom eCommerce Apps
• Configuring User and Application Data Access
• Ad-Hoc Products