Create a Ship / Receive eventReceiving a Lot

Receive a Lot

Receive a Lot. 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": "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": "Created",
      "eventDate": "2024-03-30T18: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 Receive event records when a lot is received into a Wholechain location.


The Receive event identifies:


    

  • where the product came from using ShipFromLocation
    • 

  • where the product was received using ShipToLocation
    • 

  • which product and lot were received using ProductInstances
    • 

  • how much product was received using Quantity
    • 

  • when the event occurred using EventTime
    • 

  • the unique identifier of the Receive event using Id
    • 



A Receive event can be used when receiving product from another Wholechain user, from an external supplier, or when starting the traceability journey at the point of receipt.




Request Headers


HeaderDescriptionExample Value
X-API-KEYYour API key.YOUR_API_KEY_HERE
Content-TypeContent type of the request.application/json
acceptResponse content type.*/*




Request Body


Event Object


FieldTypeDescriptionRequired
$typeSTRINGDefines the event type. For a Receive event, use receive.Yes
ShipFromLocationOBJECTLocation the product was received from.Yes
ShipToLocationOBJECTInternal location receiving the product.Yes
ProductInstancesARRAYProducts and lots being received.Yes
IdSTRINGUnique identifier for the Receive event.Yes
PurchaseOrderSTRINGPurchase order associated with the event.No
InvoiceNumberSTRINGInvoice number associated with the event.No
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.Yes
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.No
ShipEventIdSTRINGID of the specific Ship event being received, when applicable.No


The Receive API requires the event Id and EventTime. EventTimeZone, purchase order, invoice number and ShipEventId are optional.




Ship From Location


ShipFromLocation identifies where the lot came from.


The location and associated trade partner are included directly in the Receive payload.


"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": "Contact Name",
      "Phone": "+1234567890",
      "Email": "contact@example.com"
    },
    "Address": {
      "City": "City Name",
      "State": "State Name",
      "Country": "Country Name",
      "AddressLine1": "123 Supplier Street",
      "AddressLine2": "Building 2",
      "PostalCode": "12345",
      "GeoCoordinates": {
        "Latitude": 12.345678,
        "Longitude": 98.765432
      }
    }
  }
}



Location Fields


FieldTypeDescriptionRequired
IdSTRINGUnique identifier for the location.Yes
DetailsOBJECTDetails associated with the location.Required only if the location does not already exist
Details.TradePartnerOBJECTTrade partner associated with the location.Yes
Details.TradePartner.IdSTRINGUnique identifier for the trade partner.Yes
Details.TradePartner.NameSTRINGName of the trade partner.Yes
Details.TradePartner.ConnectionTypeSTRINGRelationship type, e.g. SUPPLIER, BUYER, SELF, or OTHER.Yes
Details.TradePartner.DunsSTRINGDUNS number of the trade partner.No
Details.NameSTRINGName of the location.Yes
Details.GlnSTRINGGlobal Location Number.No
Details.ExtensionSTRINGAdditional location information.No
Details.ContactInformationOBJECTContact information associated with the location.No
Details.ContactInformation.NameSTRINGContact person's name.No
Details.ContactInformation.PhoneSTRINGContact phone number.No
Details.ContactInformation.EmailSTRINGContact email address.No
Details.AddressOBJECTAddress of the location.Yes
Details.Address.CitySTRINGCity.No
Details.Address.StateSTRINGState or province.No
Details.Address.CountrySTRINGCountry.Yes
Details.Address.AddressLine1STRINGPrimary address line.Yes
Details.Address.AddressLine2STRINGSecondary address line.No
Details.Address.PostalCodeSTRINGPostal code.No
Details.Address.GeoCoordinatesOBJECTGeographic coordinates.No
Details.Address.GeoCoordinates.LatitudeDECIMALLatitude.No
Details.Address.GeoCoordinates.LongitudeDECIMALLongitude.No


The Receive API supports these location, trade partner, contact, address, and geographic fields in the location Details structure.




Ship To Location


ShipToLocation identifies the location receiving the lot.


It uses the same location structure as ShipFromLocation.


For your own location, the associated trade partner will normally use:


"ConnectionType": "SELF"





Product Instances


ProductInstances identifies the product, lot number, and quantity being received.


Each lot should be represented as a separate object in the ProductInstances array.


Duplicate lot numbers should not be submitted as separate product instances within the same event. If the same lot appears multiple times, combine the quantities into a single product instance.


Product Instance Fields


FieldTypeDescriptionRequired
QuantityDECIMALQuantity of the lot being received.Yes
LotSerialSTRINGLot or batch number.Yes
ProductOBJECTProduct associated with the lot.Yes
Product.IdSTRINGUnique identifier for the product.Yes
Product.DetailsOBJECTProduct details.Required only if the product does not already exist
Product.Details.NameSTRINGName of the product.Yes
Product.Details.SimpleUnitOfMeasurementSTRINGUnit in which the product is measured.Yes
Product.Details.SharingPolicySTRINGSharing policy, e.g. Open or Restricted.Yes
Product.Details.ProductIdentifierTypeSTRINGProduct identifier type. For this event use Lot.Yes
Product.Details.UnitQuantityDECIMALQuantity contained in the commercial or packaging unit.No
Product.Details.UnitDescriptorSTRINGCommercial or packaging unit: Cases, Units, Totes or Pallets.No
Product.Details.GtinSTRINGGlobal Trade Item Number.No
Product.Details.PluSTRINGPrice Lookup Code.No
Product.Details.MasterDataARRAYCustom data associated with the product.No




Product Custom Data


See Event and Lot Custom Data.




Receiving a Specific Ship Event


When the Receive event relates to a specific Ship event already recorded in Wholechain, include ShipEventId.


"ShipEventId": "ship_0003"



For the Receive to succeed:


    

  • The Ship exists and has not been received yet; otherwise 422 "The shipment was already received." or 404 "No pending ship event found with ExternalEventId matching ShipEventId: <id>".
    • 

  • The Ship EventTime is earlier than the Receive EventTime; otherwise 409 "Event time must be greater than the previous event."
    • 

  • Each Receive line has the same LotSerial and Quantity as the Ship; otherwise 422 "Receive line for lot '<lot>' does not match the referenced ship."
    • 

  • ShipToLocation equals the Ship's ShipToLocation; otherwise 422 "Receive location does not match the ship destination."
    • 



When ShipEventId is provided, the ProductInstances on the Receive event are ignored. The product instances from the referenced Ship event are recorded instead.




Example Receive a Lot Payload — All Fields


The example below shows the standard Receive a Lot payload including all supported location, product, and event fields covered in this documentation.


Fields that are not applicable should be omitted rather than submitted with empty values.


{
  "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": "City Name",
            "State": "State Name",
            "Country": "Country Name",
            "AddressLine1": "123 Supplier Street",
            "AddressLine2": "Building 2",
            "PostalCode": "12345",
            "GeoCoordinates": {
              "Latitude": 12.345678,
              "Longitude": 98.765432
            }
          }
        }
      },
      "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": "City Name",
            "State": "State Name",
            "Country": "Country Name",
            "AddressLine1": "456 Warehouse Road",
            "AddressLine2": "Unit 4",
            "PostalCode": "54321",
            "GeoCoordinates": {
              "Latitude": 12.345679,
              "Longitude": 98.765433
            }
          }
        }
      },
      "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_0001",
      "ShipEventId": "ship_0003",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2026-09-24T10:00:00",
      "EventTimeZone": "+00:00"
    }
  ]
}





Certifications and Custom Event Data


Certifications and custom event-level data are supported but are documented separately.


→ See: Certifications


For information on adding certification records to an event, see the dedicated Certifications documentation.


→ See: Custom Event Data


For information on adding custom fields directly to an event using CustomProperties, see the dedicated Custom Event Data documentation.


These are separate from Product.Details.MasterData, which stores custom information against the product rather than the individual Receive event.




How Entity Creation Works


Locations, trade partners, and products can all be supplied directly within the Receive payload.


The API uses the supplied IDs to determine whether the entity already exists:


    

  • If the ID does not exist, Wholechain creates the entity using the supplied Details.
    • 

  • If the ID already exists, Wholechain uses the existing entity associated with that ID.
    • 

  • Locations, trade partners, and products can therefore all use the same standard payload structure.
    • 



If an ID already exists, the API uses the existing entity rather than updating it using the supplied Details.




Important Notes


    

  • A Receive event must identify the sending location, receiving location, product lot, quantity, event ID, and event time.
    • 

  • ProductIdentifierType should be Lot when receiving a lot.
    • 

  • Each lot should appear only once within the same event.
    • 

  • If the same lot appears multiple times, combine its quantities into a single ProductInstances object.
    • 

  • Locations, trade partners, and products are included directly within the standard Receive payload.
    • 

  • Optional location, product, and event fields should be omitted when they do not apply.
    • 

  • MasterData stores custom information against the product.
    • 

  • Event-level custom data and certifications are documented separately.
    • 

  • Use ShipEventId when the Receive is intended to receive a specific existing Ship event.
    • 

Was this page helpful?