Inventory snapshot events V2

Edit online

Inventory snapshot events are triggered when an inventory snapshot is captured in Store Inventory Management at a particular point in time. Using Inventory snapshot events V2, you can have multiple messages of your captured data.

To reliably use Inventory snapshot V2 messages, it's important to understand how to identify and correctly handle snapshot data through individual snapshot messages. You can create a schedule of this everyday activity and use this feature to take a snapshot of the inventory data in that point in time.

Key identifiers

You can identify each unique snapshot for a store with these combinations:
  • tenantId
  • storeId
  • timestamp

This combination maps to a uniquebatchId, which is used to track all snapshot messages belonging to that specific store snapshot.

Processing snapshot messages

Sequencing
  • Every snapshot message includes a messageSequence indicating its position in the snapshot stream.
  • The final message in the batch includes a totalMessages field, representing the total number of expected unique snapshot messages. In this final message, the data field is empty. The final message serves to indicate completion of the snapshot.
  • All preceding messages have this field empty.
Out-of-order delivery
  • Snapshot messages might arrive out of order.
  • Your system must track messageSequence values per batchId to ensure that all expected messages have been received.
  • A snapshot is considered complete when the count of unique messageSequence values matches the totalMessages field in the final message.
Deduplication
  • A snapshot message might be published more than once resulting in duplicates.
  • If two messages share the same messageSequence and identical timestamp for a particular batchId, they are considered duplicates.
  • You can safely discard one of them.
Latest timestamp preference
  • Sometimes, multiple snapshot messages might arrive with the same messageSequence but different timestamps for the same store.
  • In such cases, you must retain and process the message with the most recent timestamp.
  • Older versions of that sequence can be safely discarded.

This sequence of steps helps ensure that your system reflects the most recent snapshot state.

Example flows
Store1 - Working with duplicate messages (the same timestamp)

A snapshot is generated for Store1. The system receives:

Snapshot Message 1: messageSequence = 1, totalMessages = "", timestamp = 2024-10-10T08:00Z
 
Snapshot Message 2: messageSequence = 2, totalMessages = "", timestamp = 2024-10-10T08:00Z
Snapshot Message 3: messageSequence = 2, totalMessages = "", timestamp = 2024-10-10T08:00Z ← Duplicate
 
Snapshot Message 4: messageSequence = 3, totalMessages = "3", timestamp = 2024-10-10T08:00Z

Message 2 and 3 are duplicates. Since both have the same sequence and timestamp, discard one.

Store2 - Using the most recent timestamp preference

A snapshot is generated for Store2. The system receives:

Snapshot Message 1: messageSequence = 1, totalMessages = "", timestamp = 2024-10-10T08:00Z
Snapshot Message 2: messageSequence = 2, totalMessages = "", timestamp = 2024-10-10T08:00Z
Snapshot Message 3: messageSequence = 1, totalMessages = "", timestamp = 2024-10-10T08:10Z
 
Snapshot Message 4: messageSequence = 2, totalMessages = "", timestamp = 2024-10-10T08:10Z 
Snapshot Message 5: messageSequence = 3, totalMessages = "3", timestamp = 2024-10-10T08:10Z

Here, use the most recent snapshot messages (messages 3, 4, and 5). Discard the older ones (messages 1 and 2), because they are outdated.

Snapshot messages might arrive out of order. Because of this action, your system must track and validate each snapshot message by its sequence number and batchId metadata before marking a snapshot as complete.

The following JSON example shows a published event that is generated when an inventory snapshot is captured. The application encodes and adds the event data to the messages[].data JSON path. 
{
"messages": [
{
"data": [
{
"productId": "100001",
"unitOfMeasure": "EACH",
"inventoryStatus": "GOOD",
"productClass": "",
"segmentType": "",
"segment": "",
"tagNo": "",
"batchNo": "",
"lotNo": "",
"manufacturedDate": "",
"locationId": "Bin1",
"quantity": 9.0
},
{
"productId": "100002",
"unitOfMeasure": "EACH",
"inventoryStatus": "GOOD",
"productClass": "",
"segmentType": "",
"segment": "",
"tagNo": "",
"batchNo": "",
"lotNo": "",
"manufacturedDate": "",
"locationId": "FoH",
"quantity": -1.0
}
],
"attributes": {
"code": "inventorySnapshotV2",
"timestamp": "2024-10-10T08:00Z[Etc/UTC]",
"messageId": "17d03402-7176-49df-9dc5-b0c25c22f310",
"batchId": "1692ae82-25f9-4943-b4d6-79458077925e",
"totalMessages": "1",
"messageSequence": "1",
"storeId": "Store1",
"groupBy": ""
}
}
]
}
The following example shows the JSON schema specification that defines the structure of the JSON data that is published to the inventorySnapshotV2 event. 
{
"properties": {
"messages": {
"type": "array",
"description": "Array containing the message details",
"items": {
"type": "object",
"properties": {
"data": {
  "type": "array",
  "description": "Array containing the inventory details",
  "items": {
    "type": "object",
    "properties": {
      "productId": {
        "type": "string",
        "description": "Unique identifier of the product"
      },
      "unitOfMeasure": {
        "type": "string",
        "description": "Unit of measure for the product"
      },
      "inventoryStatus": {
        "type": "string",
        "description": "Status of the inventory (e.g., GOOD)"
      },
      "productClass": {
        "type": "string",
        "description": "Classification of the product"
      },
      "segmentType": {
        "type": "string",
        "description": "Type of segment for the product"
      },
      "segment": {
        "type": "string",
        "description": "Segment details of the product"
      },
      "tagNo": {
        "type": "string",
        "description": "Tag number for the product"
      },
      "batchNo": {
        "type": "string",
        "description": "Batch number for the product"
      },
      "lotNo": {
        "type": "string",
        "description": "Lot number for the product"
      },
      "manufacturedDate": {
        "type": "string",
        "description": "Manufacturing date of the product"
      },
      "locationId": {
        "type": "string",
        "description": "Location identifier where the product is stored"
      },
      "quantity": {
        "type": "number",
        "description": "Quantity of the product in stock"
      }
    }
  }
},
"attributes": {
  "type": "object",
  "description": "Object containing the event attributes",
  "properties": {
    "code": {
      "type": "string",
      "description": "Code representing the event"
    },
    "timestamp": {
      "type": "string",
      "description": "The exact time when the snapshot was taken"
    },
    "messageId": {
      "type": "string",
      "format": "uuid",
      "description": "A unique identifier for the event message"
    },
    "batchId": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier of a store batch"
    },
    "totalMessages": {
      "type": "string",
      "description": "The total number of messages for this store (for pagination)"
    },
    "messageSequence": {
      "type": "string",
      "description": "Page number of the current message"
    },
    "storeId": {
      "type": "string",
      "description": "Unique identifier of the store"
    },
    "groupBy": {
      "type": "string",
      "description": "Attribute used for grouping the data"
    }
  }
}
}
}
}
}
}

For more information, see the Create inventory snapshot scheduled for the associated stores API.