EventsUpdate an event

Update an Event

Overrides an existing event using the complete documented Receive event payload.

curl -X POST "https://connect.wholechain.com/Integration/Events" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: example_string" \
  -d '{
  "Events": [
    {
      "$type": "receive",
      "ShipFromLocation": {
        "Id": "supplier_location_001",
        "Details": {
          "TradePartner": {
            "Id": "supplier_001",
            "Name": "Supplier Name",
            "ConnectionType": "SUPPLIER",
            "Duns": "123456789"
          },
          "Name": "Supplier Location",
          "Gln": "9506000140445",
          "Extension": "SomeExtension",
          "ContactInformation": {
            "Name": "Supplier Contact",
            "Phone": "+1234567890",
            "Email": "supplier@example.com"
          },
          "Address": {
            "City": "Cape Town",
            "State": "Western Cape",
            "Country": "South Africa",
            "AddressLine1": "123 Supplier Street",
            "AddressLine2": "Building 2",
            "PostalCode": "8001",
            "GeoCoordinates": {
              "Latitude": -33.9249,
              "Longitude": 18.4241
            }
          }
        }
      },
      "ShipToLocation": {
        "Id": "warehouse_001",
        "Details": {
          "TradePartner": {
            "Id": "my_company",
            "Name": "My Company",
            "ConnectionType": "SELF",
            "Duns": "987654321"
          },
          "Name": "Main Warehouse",
          "Gln": "9506000140446",
          "Extension": "WarehouseExtension",
          "DunsPlus4": "1234",
          "ContactInformation": {
            "Name": "Warehouse Contact",
            "Phone": "+1234567891",
            "Email": "warehouse@example.com"
          },
          "Address": {
            "City": "Cape Town",
            "State": "Western Cape",
            "Country": "South Africa",
            "AddressLine1": "456 Warehouse Road",
            "AddressLine2": "Building 2",
            "PostalCode": "8002",
            "GeoCoordinates": {
              "Latitude": -33.925,
              "Longitude": 18.425
            }
          }
        }
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "lot_001",
          "Product": {
            "Id": "product_001",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Sample Product",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "Gtin": "12345678912343",
              "Plu": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          }
        }
      ],
      "Id": "receive_lot_001",
      "ShipEventId": "ship_lot_001",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T18:00:00",
      "EventTimeZone": "-05:00",
      "CustomProperties": [
        {
          "Name": "quality_grade",
          "Namespace": "custom",
          "Value": "A"
        }
      ],
      "CertificationList": [
        {
          "Type": "urn:gdst:certType:harvestCoC",
          "Standard": "MSC Chain of Custody",
          "Agency": "MSC",
          "Value": "YES",
          "Identification": "MSC-C-12345"
        }
      ]
    }
  ]
}'

{
  "message": "Events processed successfully",
  "result": [
    {
      "id": "01a0d877-7871-79a5-a8c8-a2f45673633d",
      "externalEventId": "receive_lot_001",
      "type": "Receive",
      "status": "Overridden",
      "eventDate": "2024-03-30T18:00:00+00:00",
      "productInstances": [
        {
          "quantity": 190.75,
          "lotSerial": "lot_001",
          "status": "Overridden",
          "id": "01a0d877-7871-7426-b365-3a587ad4f893",
          "name": "Raw Goods",
          "urn": "urn:gdst:wholechain.com:product:lot:class:raindropsolutions.rawgoods-1.lot_001"
        }
      ],
      "containers": [],
      "directShipFallback": null,
      "externalShipmentFailure": null
    }
  ],
  "locations": [
    {
      "id": "01a0d877-76de-7e96-ac8c-962a914952bf",
      "status": "Created"
    }
  ],
  "products": [
    {
      "id": "01a0d877-7719-720e-8fd8-224e3fec0602",
      "status": "Created"
    }
  ],
  "errors": [],
  "validations": []
}
POST
/Integration/Events
POST
Base URLstring

Target server for requests. Edit to use your own host.

Content-Typestring
Required

The media type of the request body

Options: application/json
header
X-API-KEYstring
Required

API key used to authenticate the request.

Eventsarray
Required

Required. events.

Request Preview
Response
Response will appear here after sending the request


Responses


messagestring
Optional. message.
resultarray
Optional. result.
locationsarray
Optional. locations.
productsarray
Optional. products.
errorsobject[]
Optional. errors.
validationsobject[]
Optional. validations.


Introduction


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. 

  2. Event overwriting to be enabled
    3. 



How to Configure This


    

  1. Navigate to Settings
    2. 

  2. Select Account
    3. 

  3. Toggle Enable Blockchain → OFF
    4. 

  4. Toggle Event Overwriting → ON
    5. 



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.




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. 

  2. The new payload replaces the previous event entirely
    3. 



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",
      "EventTimeZone": "-05:00"
    }
  ]
}






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",
      "EventTimeZone": "-05:00",
    }
  ]
}




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


    

  • 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.
Was this page helpful?