Create a Ship / Receive eventReceiving a Container

Receive a Container

Receive a Container. 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": "processing_001",
        "Details": {
          "TradePartner": {
            "Id": "processor_001",
            "Name": "Processor Name",
            "ConnectionType": "SELF",
            "Duns": "123456789"
          },
          "Name": "Processing Facility",
          "Gln": "9506000140445",
          "Extension": "SomeExtension",
          "DunsPlus4": "1234",
          "ContactInformation": {
            "Name": "Processing Contact",
            "Phone": "+1234567890",
            "Email": "processing@example.com"
          },
          "Address": {
            "City": "Cape Town",
            "State": "Western Cape",
            "Country": "South Africa",
            "AddressLine1": "123 Processing 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": [],
      "Container": {
        "Id": "container_001",
        "Type": "LogisticId"
      },
      "Id": "receive_container_001",
      "ShipEventId": "ship_container_001",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T18:30: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_container_001",
      "type": "Receive",
      "status": "Created",
      "eventDate": "2024-03-30T18:30: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": [
        {
          "id": "container_001",
          "status": "Created"
        }
      ],
      "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 Container event records when a container is received into a Wholechain location.


The Receive event identifies:


    

  • where the container came from using ShipFromLocation
    • 

  • where the container was received using ShipToLocation
    • 

  • which container was received using Container
    • 

  • when the event occurred using EventTime
    • 

  • the unique identifier of the Receive event using Id
    • 



When receiving a container, the products contained within the container do not need to be listed individually in ProductInstances. The container is referenced using its Id.




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 container was received from.Yes
ShipToLocationOBJECTLocation receiving the container.Yes
ProductInstancesARRAYProduct instances being received. Leave this empty when receiving only a container.No
ContainerOBJECTContainer being received.Yes
IdSTRINGUnique identifier for the Receive event.Yes
ShipEventIdSTRINGID of the specific Ship event being received, when applicable.No
PurchaseOrderSTRINGPurchase order associated with the Receive event.No
InvoiceNumberSTRINGInvoice number associated with the Receive 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




Ship From Location


ShipFromLocation identifies where the container came from.


The location and its associated trade partner can be included directly in the Receive event.


"ShipFromLocation": {
  "Id": "processing_000",
  "Details": {
    "TradePartner": {
      "Id": "TpId123",
      "Name": "Me",
      "ConnectionType": "SELF",
      "Duns": "123456789"
    },
    "Name": "Processing",
    "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 Main St",
      "AddressLine2": "Apt 4B",
      "PostalCode": "12345",
      "GeoCoordinates": {
        "Latitude": 12.345678,
        "Longitude": 98.765432
      }
    }
  }
}





Ship To Location


ShipToLocation identifies the location receiving the container.


It uses the same location structure as ShipFromLocation.


"ShipToLocation": {
  "Id": "buyer_000",
  "Details": {
    "TradePartner": {
      "Id": "buyer_123",
      "Name": "BuyerTP",
      "ConnectionType": "BUYER",
      "Duns": "123456789"
    },
    "Name": "Buyer Location",
    "Gln": "9506000140445",
    "Extension": "SomeExtension",
    "DunsPlus4": "1234",
    "ContactInformation": {
      "Name": "Contact Name",
      "Phone": "+1234567890",
      "Email": "contact@example.com"
    },
    "Address": {
      "City": "City Name",
      "State": "State Name",
      "Country": "Country Name",
      "AddressLine1": "123 Main St",
      "AddressLine2": "Apt 4B",
      "PostalCode": "12345",
      "GeoCoordinates": {
        "Latitude": 12.345678,
        "Longitude": 98.765432
      }
    }
  }
}





Location Fields


The same location structure can be used for both ShipFromLocation and ShipToLocation.


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.DunsPlus4STRINGDUNS Plus 4 identifier, if applicable.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




Container


The Container object identifies the container being received.


"Container": {
  "Id": "123456"
}



Container Fields


FieldTypeDescriptionRequired
IdSTRINGUnique identifier for the container being received.Yes


The container must already exist from a previous container creation, aggregation, or shipment event.


When receiving a container, ProductInstances should remain empty:


"ProductInstances": []



The products associated with the container are identified through the container itself.




Receiving a Specific Ship Event


When the container was previously shipped through Wholechain, ShipEventId can be used to identify the specific Ship event being received.


"ShipEventId": "ship_0003"



Use this when the Receive event should be directly connected to a specific pending shipment.


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 Container Payload — All Fields


The following example shows the standard Receive Container payload with all supported location, container, 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": "processing_000",
        "Details": {
          "TradePartner": {
            "Id": "TpId123",
            "Name": "Supplier Name",
            "ConnectionType": "SUPPLIER",
            "Duns": "123456789"
          },
          "Name": "Processing 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 Main St",
            "AddressLine2": "Apt 4B",
            "PostalCode": "12345",
            "GeoCoordinates": {
              "Latitude": 12.345678,
              "Longitude": 98.765432
            }
          }
        }
      },
      "ShipToLocation": {
        "Id": "buyer_000",
        "Details": {
          "TradePartner": {
            "Id": "buyer_123",
            "Name": "My Company",
            "ConnectionType": "SELF",
            "Duns": "987654321"
          },
          "Name": "Receiving Location",
          "Gln": "9506000140446",
          "Extension": "SomeExtension",
          "DunsPlus4": "1234",
          "ContactInformation": {
            "Name": "Receiving Contact",
            "Phone": "+1234567891",
            "Email": "receiving@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": [],
      "Container": {
        "Id": "123456"
      },
      "Id": "receive_container_0001",
      "ShipEventId": "ship_0003",
      "PurchaseOrder": "1990091",
      "InvoiceNumber": "12314154",
      "EventTime": "2026-09-24T10:00:00",
      "EventTimeZone": "+00:00"
    }
  ]
}





Certifications and Custom Event Data


Certifications and custom event-level data can also be added to a Receive Container event but are documented separately.


→ See: Certifications


For information on attaching certifications to an event, see the dedicated Certifications documentation.


→ See: Custom Event Data


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




How Location Creation Works


Locations and trade partners are supplied directly within the standard Receive payload.


The API uses the supplied IDs to determine whether they already exist:


    

  • If the location or trade partner ID does not exist, Wholechain creates it using the supplied Details.
    • 

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

  • The same payload structure can therefore be used for both new and existing locations and trade partners.
    • 





Important Notes


    

  • Use $type: "receive" when receiving a container.
    • 

  • ShipFromLocation identifies where the container came from.
    • 

  • ShipToLocation identifies where the container is being received.
    • 

  • Use Container.Id to identify the container being received.
    • 

  • When receiving only a container, ProductInstances should be an empty array.
    • 

  • The contents of the container do not need to be listed individually in the Receive event.
    • 

  • PurchaseOrder and InvoiceNumber are optional.
    • 

  • Use ShipEventId when receiving against a specific existing Ship event.
    • 

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

  • Certifications and custom event data are documented separately.
    • 

Was this page helpful?