Simple Update in GS1 API

5 min

This document outlines the usage of the simpleUpdate feature in the GS1 API for creating, upserting, or updating an order.

Earlier Scenario: Whenever an order was created through the API, all fields used to be upserted, regardless of whether the order already existed. There was no way to update only specific fields for an existing order. To address this, the simpleUpdate approach was introduced.

Current Scenario: To address the shortcomings of the previous design, a flag called simpleUpdate has been introduced in the API. This flag takes a boolean value, either true or false, to determine whether the condition is a create, upsert, or update. By default, if simpleUpdate is not provided in the API request, it will be treated as true, meaning that by default, simpleUpdate is true.

How does it work in practice?

In practice, the simpleUpdate flag allows for more granular control over the update process. When set to false, the API will update only the provided fields of an existing order, leaving all other fields intact. If set to true, a create condition occurs if an order was not previously existing and if an order was existing then an upsert condition occurs, potentially overwriting all fields, similar to the original behavior. If the flag is omitted, then also the value of the flag will be considered as true.

Create

If an order is unique and the flag is true then that will be considered as a create scenario.

If the flag is not present or if "simpleUpdate":true is sent in the api then a new order will be created with the given details in the payload.

If the flag is sent as "simpleUpdate":false , it will result in an error "Order not found" as we are trying to update with false flag for an order that does not pre-exist.

{
    "orderNumber": "Order_14Sept_3",
    "simpleUpdate":true,//If this flag is not present then by default,value is true
    "orderTypeCode": "PO",
    "paymentMethod": "prepaid",
    "orderPriority": "HIGH",
    "status": "dispatch",
    "orderStatusCode": "000123ABC",
    "transportType": "International",
    "paymentMethodCode": "Collect",
    "requiredDeliveryDateTime": "2024-08-25T11:00:27.464596Z",
    "originalRequiredDeliveryDate": "2024-08-25T11:00:27.464596Z",
    "lineItems": [
        {
            "itemName": "Memory NAND FLASH PLASTIC",
            "lineItemNumber": "MT29F8G01ADBFD12-AAT:F88",
            "itemDescription": "Integrated Circuits - Memory NAND FLASH PLASTIC",
            "holdDate": "2021-02-12T11:00:27.464596Z",
            "weightUnit": "EA",
            "product": {
                "productId": "MT29F8G01ADBFD12-AAT:F",
                "productSku": "MT29F8G01ADBFD12-AAT:F"
                }
            }
    ]
}

Upsert

If an order is pre-existing and the flag is true then that will be considered as an upsert scenario.

If the flag is not present or if "simpleUpdate":true is sent in the api for an existing order then that will be considered as an upsert condition. For eg like in the sample payload below I have added some more fields and removed one field from the create payload we had above and now if we try to hit this the order will get upserted with all the new details being provided in the below payload.

{
    "orderNumber": "Order_14Sept_3",
    "simpleUpdate":true,//If this flag is not present then by default,value is true
    "orderTypeCode": "PO",
    "paymentMethod": "prepaid",
    "orderPriority": "HIGH",
    "status": "dispatch",
    "orderStatusCode": "000123ABC",
    "transportType": "International",
    "transportType": "International",
    "currencyCode": "USD",
    "orderEntryType": "MOBILE",
    "paymentMethodCode": "Collect",
    "requiredDeliveryDateTime": "2024-08-25T11:00:27.464596Z",
    "originalRequiredDeliveryDate": "2024-08-25T11:00:27.464596Z",
    "reasonCode": "reason",
    "releaseDate": "2021-02-28T11:00:27.464596Z",
    "lineItems": [
        {
            "itemName": "Memory NAND FLASH PLASTIC",
            "lineItemNumber": "MT29F8G01ADBFD12-AAT:F88",
            "itemDescription": "Integrated Circuits - Memory NAND FLASH PLASTIC",
            "holdDate": "2021-02-12T11:00:27.464596Z",
            "weightUnit": "EA",
            "product": {
                "productId": "MT29F8G01ADBFD12-AAT:F",
                "productSku": "MT29F8G01ADBFD12-AAT:F"
                }
            }
    ]
}

Update

If an order is pre-existing and the flag is false then that will be considered as an update scenario.

If the flag is "simpleUpdate":false for an existing order then it will be an update condition.

For order the mandatory field is "orderNumber" and if some fields need to be updated without changing the other fields then that can be added in the payload along with the flag as false. If no line item is given in the payload then no change will be made to the line item as well.

{
    "orderNumber": "Order_14Sept_3",
    "simpleUpdate":false //If this flag is not present then by default,value is true
}

If an existing line item needs to be updated then the composite key of "lineItemNumber" ,"productId", "productSku" and "productUpc" should be the same and other fields which needs to be updated can be added along with the composite key fields in the payload.

If a new line item needs to be added keeping the earlier line item (if any) intact then the same composite key should be made different and unique, while other fields can be added along for the new line item in the payload.

"lineItems": [
        {
            "itemName": "Memory NAND FLASH PLASTIC",
            "lineItemNumber": "MT29F8G01ADBFD1111",
            "itemDescription": "Integrated Circuits - Memory NAND FLASH PLASTIC",
            "holdDate": "2021-02-12T11:00:27.464596Z",
            "weightUnit": "EA",
            "product": {
                "productId": "MT29F8G01ADBFD12-AAT1000111",
                "productSku": "MT29F8G01ADBFD12-AAT1117"
                "productUpc": "MT29F8G01ADBFD12-AAT99"
                }
            }
    ]