Summary

A secondary key is an alternate key which can be used in addition to the primary key to locate specific product data. For example, this can be useful if clients sell products with the same product ID, but at different unit prices.

While a primary key uniquely identifies each record in a table, the secondary keys help speed up the retrieval of data based on other columns. This is especially useful when you need to search for records using criteria other than the primary key.

In the example below, an order was placed, and two different secondary keys were passed to differentiate the products purchased.

Secondary Key Requirement:

• Some clients use product ID and quantity as keys to identify which product is being returned or canceled from an order. They don’t face any issues as the product ID works as a unique key for them. However, in the case of some clients, the product ID does not act as a unique key. There could be multiple products in a single order with the same product ID, with different unit prices and product attributes. In such a scenario, when the return of a product is generated, the system fails to identify which line of product to update as both have the same product ID.
  

For example, in an order, there are three products with the same ID and quantity but different prices. Once the order has been shipped, the member wishes to return the $30 merchandise. In this instance, the system checks the order using the ID, but because all three products have the same ID, the system becomes confused and displays an error.

To address these concerns, a new option, a secondary key, can be added, through which you can provide a unique value that can differentiate all the items, and the system can easily process the cancel or return of the product.

Configuring a Secondary Key

Navigation: Products >Actions > Action Rules > Advanced Settings > Additional Settings > Enable Secondary Key for Product

Turn ON the secondary key flag within the Order API Settings. Then go to the Order API and pass the secondary key parameter under the order detail array for the product you would like to have the secondary key. The order detail array contains required parameters such as ID, quantity, unit price, estimated shipping date, and description.

All the records for the secondary key will be stored in the database. If the flag is OFF and you try to pass the secondary key in the order API payload, no records will be stored in the database.

If the flag is ON and the secondary key is not passed in the order API payload, the API will return a validation error since a secondary key value is necessary for exact order mapping. Either disable the secondary key flag or pass a value.

In the order below, product ID P101 has the same secondary key for the 1st and 3rd item, and hence it returns the error message.

Test Cases

Case 1:

• Consider a scenario where the secondary key flag is OFF and the member places an order. By mistake, the client passes the secondary key for each product. (Note: The secondary key data is not stored in the database as the flag is OFF)
• In a few days, the client turns ON the secondary key flag and the member wishes to return part of the order due to issues. While returning a product, the system does not display an error if a secondary key is passed, not passed, or wrongly passed as there is no data in the database related to the secondary key when the order was placed.

The following is an example where, by mistake, the client passes the secondary key, even though the secondary key flag is OFF:

Later, if the client turns ON the secondary key flag and a member requests a partial return of the order. While returning a product no secondary key is passed in the order API payload (as shown below), the system reports no errors, and 60 points are credited to the member's account as the merchandise is partially returned.

Case 2:

• Consider a different scenario where the secondary key flag is OFF and the member places an order. The client does not pass the secondary key for each product.
• In a few days, the client turns ON the secondary key flag and the member wishes to return part of the order due to issues. While returning a product, by mistake the client passes, does not pass, or wrongly passes the secondary key, the system does not show an error.

In the example below, the secondary key flag is OFF, and the client does not pass the secondary key as shown below:

Later, the client turns ON the secondary key flag and a member requests a partial return of the order. While returning a product no secondary key is passed in the order API payload (as shown below), the system reports no errors, and 60 points are credited to the member's account as the merchandise is partially returned.

The duplicate secondary key error message will be displayed for the two use cases below.

• Secondary key flag: ON

The secondary key also works in the following conditions: