Editing Events in Wholechain

Overview

Wholechain allows events to be updated after they have been submitted through the API. This is done by resubmitting the original event payload with the same event ID and including a special flag in the payload that instructs Wholechain whether the event should be updated.

This mechanism ensures that integrations can correct or adjust previously submitted data while maintaining the integrity of the traceability chain.

---

Required Account Settings

Before events can be edited, the account must allow event overwriting.

Editing events requires:

1. Blockchain to be disabled
2. Event overwriting to be enabled

How to Configure This

1. Navigate to Settings
2. Select Account
3. Toggle Enable Blockchain → OFF
4. Toggle Event Overwriting → ON

Once these settings are configured, events can be updated through the API.

Important: Events that were originally created before blockchain was disabled cannot be edited.
Those events remain immutable because they were committed while blockchain was enabled.

Updating Event Variable

To update an existing event, include a boolean field called updates in your payload.

Field	Type	Description
UpdateIfExists	Boolean	Determines whether an existing event with the same event ID should be updated.

Behavior

• UpdateIfExists: true Wholechain will update the existing event.

• UpdateIfExists: false Wholechain will not update the event if it already exists.

---

How Event Updates Work

Updating an event is done by resending the entire event payload using the same eventId as the original event.

How Wholechain processes an update:

1. The existing event is completely deleted
2. The new payload replaces the previous event entirely

This means that Wholechain does not merge or append data to the existing event.

Important Implication

You must resend the full event payload, including all items and data you want associated with the event.

If certain fields or items are omitted in the new payload, they will not exist in the updated event.

---

Example Workflow

Original Event Submission

{
  "Events": [
    {
      "$type": "receive",
      "ShipFromLocation": {
        "Id": "shipFrom_000"
      },
      "ShipToLocation": {
        "Id": "shipTo_000"
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "123",
          "Product": {
            "Id": "raw_goods_000"
          }
        }
      ],
      "Id": "0004",
      "EventTime": "2024-03-30T16:00:00+00:00",
      "EventTimeZone": "-05:00",
      "updates": false
    }
  ]
}

---

Updating the Event

To update the event, resend the payload with the same event Id and set updates to true.

In the example below, the lot number and product are changed.

{
  "Events": [
    {
      "$type": "receive",
      "ShipFromLocation": {
        "Id": "shipFrom_000"
      },
      "ShipToLocation": {
        "Id": "shipTo_000"
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "789",
          "Product": {
            "Id": "finished_goods_002"
          }
        }
      ],
      "Id": "0004",
      "EventTime": "2024-03-30T16:00:00+00:00",
      "EventTimeZone": "-05:00",
      "updates": true
    }
  ]
}

In this case:

• The original event with Id 0004 is deleted
• The new event payload replaces it entirely

---

Constraints When Updating Events

Event updates are subject to traceability chain validation.

Wholechain will only allow an event to be updated if the change does not break subsequent events that reference it.

Example Scenario

A Receive Event records: - Lot 456 - Quantity: 50 lbs

A Ship Event later ships: - 30 lbs from Lot 456

Attempted Update

If you attempt to update the receive event to:

• Change the lot number, or
• Reduce the quantity below 30 lbs

the update will not be allowed.

Why?

Subsequent events (such as ship or transform events) depend on the original event.
If the original event were changed in a way that invalidates those references, the traceability chain would break.

Since the update process replaces the original event, those downstream references would effectively point to an event that no longer exists or no longer satisfies the requirements of the downstream event.

For this reason, Wholechain prevents updates that would invalidate downstream events.

However, if one tried to update the receive event to instead recieve 30 pounds, the system would allow this as the ship event can still run without problems.

---

Summary

• Event updates are controlled using the UpdateIfExists flag.
• Updates require resending the full payload with the same eventId.
• Wholechain replaces the old event entirely, rather than merging data.
• Updates are only permitted if they do not invalidate subsequent events in the traceability chain.

This approach preserves both data correction flexibility and supply chain traceability integrity.