Create an EventCreate a Decommission event

Create a Decommission Event

Create a Decommission Event. The request example includes all fields documented for this event, including optional fields.

curl -X POST "https://connect.wholechain.com/Integration/Events" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: example_string" \
  -d '{
  "Events": [
    {
      "$type": "decommission",
      "Location": {
        "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": "decommission_001",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T20: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": "decommission_001",
      "type": "Decommission",
      "status": "Created",
      "eventDate": "2024-03-30T20:00:00+00:00",
      "productInstances": [
        {
          "quantity": 190.75,
          "lotSerial": "lot_001",
          "status": "Created",
          "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


A Decommission event represents the removal of a product from its documented supply chain. It typically occurs when a product is no longer active in the supply chain journey — either because it has been consumed, discarded, expired, or otherwise taken out of circulation.


How it works:


    

  • A Wholechain user can initiate a Decommission event directly from the product’s current inventory page or via the Wholechain API, with the flexibility to incorporate custom data as needed.
    • 



Practical Examples


    

  • Expired Lot Removal: A warehouse decommissions a lot of apples that have surpassed their expiration date, documenting the reason for removal and final quantities discarded.
    • 

  • Seafood Loss Event: A distributor decommissions a portion of fish inventory that was spoiled during transport, recording the lot, condition, and loss details.
    • 

  • Crop Rejection: A processor decommissions a shipment of wheat that failed quality testing, capturing the field ID, inspection results, and decommission reason.
    • 



Use Case


This API is typically used when an existing product is decommissioned (i.e., removed) from the supply chain system, ensuring transparency and accurate lifecycle tracking. The decommission event is crucial for traceability because it defines the exit of the product from the supply chain system, supporting compliance, loss reporting, and audit requirements.


Authentication


The API uses an API key (X-API-KEY) to authenticate requests. Each user has a unique API key that controls access to event details tied to their company. To understand where this can be found, please visit the Authentication page.




Request Headers for existing master data:


HeaderDescriptionExample Value
X-API-KEYYour API key<YOUR_API_KEY>
Content-TypeContent type of the requestapplication/json
acceptResponse content type*/*


Request Body Parameters:


This document outlines the  schema for the JSON event data. Each table corresponds to a distinct data object in the JSON structure.


Location Object


Column NameData TypeDescriptionIdentifierRequired
Location IDSTRINGUnique identifier for the location.PrimaryYes


Product Instance Object


Column NameData TypeDescriptionIdentifierRequired
QuantityDECIMALQuantity of the product in the instance.Not PrimaryYes
LotSerialSTRINGLot or serial number of the product instance. ⚠️ Warning: Duplicate lot numbers are not permitted within the same event. Please sum total duplicate lot quantities into one.Not PrimaryYes
Product IDSTRINGUnique identifier for the product.PrimaryYes


Event Object


Column NameData TypeDescriptionIdentifierRequired
IdSTRINGUnique identifier for the event.Not PrimaryYes
PurchaseOrderSTRINGPurchase order associated with the event.Not PrimaryNo
InvoiceNumberSTRINGInvoice number linked to the event.Not PrimaryNo
EventTimeDATETIMELocal date and time when the event occurred, without a UTC offset, for example 2024-03-30T13:00:00. The time zone is taken from EventTimeZone. Any offset included in this value is ignored.Not PrimaryYes
EventTimeZoneSTRINGOptional. Time zone of the event as a UTC offset in ±HH:MM format, for example -05:00. If omitted, the account's default time zone (selected when the account was created) is used.Not PrimaryNo




Example Payload All Fields Included


    {
    "Events": [
        {
            "$type": "decommission",
            "Location": {
                "Id": "4567"
            },
            "ProductInstances": [
                {
                    "Quantity": 190.75,
                    "LotSerial": "1990091",
                    "Product": {
                        "Id": "prod_000"
                    },
                    "TraceabilityLotCode": "1234567989",
                    "TlcSource": {
                        "Type": "Identifier",
                        "Reference": "Eg: BAP",
                        "Identifier": "BAP01283"
                    }
                }
            ],
            "Id": "0082932",
            "PurchaseOrder": "1990091",
            "InvoiceNumber": "12314154",
            "EventTime": "2024-03-30T13:00:00",
            "EventTimeZone": "-05:00",
            "CustomProperties": [
                {
                    "Name": "expiry_date",
                    "Namespace": "custom",
                    "Value": "2024-03-30"
                }
            ],
            "CertificationList": [
                {
                    "Type": "urn:gdst:certType:harvestCoC",
                    "Standard": "MSC Chain of Custody",
                    "Agency": "MSC",
                    "Value": "NO",
                    "Identification": "NA"
                }
            ]
        }
    ]
}


Was this page helpful?