Uniqueness Keys

Uniqueness keys dictate which attributes make each resource distinct. The RepSpark API automatically assigns internal numeric identifiers based on these attributes. For example, each Product might be uniquely identified by its product number attribute, or possibly product number and color code, or product number, color code, and gender, and so on. This step requires you to fully understand your data.

We recommend that you use the fewest attributes possible to define the uniqueness of each resource. For example, for Products, we recommend not using season as a uniqueness key component, otherwise Products with the same product number and color code would be different across different seasons. This means every time the season attribute changes on a product, the internal identifier in RepSpark also changes which will result in potential errors.

However, in the case that you would like to have product number and color code combinations treated as completely distinct Products across seasons, then you should include season as a uniqueness key component.
When a uniqueness key is formed, all values are made uppercase. In other words, uniqueness keys are case-insensitive. For example, if a color code changes from red to RED, the internal numeric identifier will remain the same.

The RepSpark web and mobile apps depend on the long-term consistency of the internal numeric identifiers mapped from these uniqueness keys. Unplanned changes to the data that comprise these keys, such as transforming season codes S23 and F23 into SP23 and FA23 when season code is defined as a uniqueness key component, may break orders, catalogs, assortments, and microsites.

With the exception of Inventory records, as Inventory can have multiple records representing future dates, resources, like Customers, Products, Options, and Reports, cannot have records with identical uniqueness keys.

📘

In summary, if an attribute's value changes, but the resource itself is intended to not change, do not include that attribute as a uniqueness key component.

The attributes that define the uniqueness key of a resource are defined early in the integration before any data is sent to the RepSpark API. Please contact RepSpark Professional Services to discuss the setup of uniqueness keys.

For example, consider the following two Customer records:

The RepSpark API internally combines each column value to form the uniqueness key for each Customer resource, such as A01_USA_SMTH_JAK1_NOR99_TRUE. If we remove BrandCode from the Customer uniqueness keys, these two records would generate the same key and return a duplicates error from the API.