Create a Ship / Receive eventShipping a Container

Ship a Container

Ships an existing container. ProductInstances must be an empty array because the products are identified through the container.

curl -X POST "https://connect.wholechain.com/Integration/Events" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: example_string" \
  -d '{
  "Events": [
    {
      "$type": "ship",
      "ShipFromLocation": {
        "Id": "processing_000"
      },
      "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
            }
          }
        }
      },
      "ProductInstances": [],
      "Container": {
        "Id": "123456"
      },
      "Id": "0004",
      "PurchaseOrder": "1990091",
      "InvoiceNumber": "12314154",
      "EventTime": "2024-03-30T16: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"
        },
        {
          "Type": "urn:gdst:certType:fishingAuth",
          "Standard": "Los Angeles Fishing Authorization",
          "Agency": "Los Angeles Fishing Authorization",
          "Value": "YES",
          "Identification": "FA-2024-001"
        },
        {
          "Type": "urn:gdst:certType:humanPolicy",
          "Standard": "WHO Human Decency Policy",
          "Agency": "WHO",
          "Value": "YES",
          "Identification": "WHO-2024-001"
        }
      ]
    }
  ]
}'

{
  "message": "Events processed successfully",
  "result": [
    {
      "id": "01a0d877-7871-79a5-a8c8-a2f45673633d",
      "externalEventId": "ship_container_001",
      "type": "Ship",
      "status": "Created",
      "eventDate": "2024-03-30T16:00:00+00:00",
      "productInstances": [],
      "containers": [
        {
          "id": "123456",
          "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 Ship Container event records the movement of an existing container from one Location to another.


A container shipment can represent either:


    

  • Internal movement — for example, shipping a container from one warehouse to another Location within your business.
    • 

  • External movement — for example, shipping a container from your Location to a customer, buyer, or other external Trade Partner.
    • 



The event identifies:


    

  • The container being shipped
    • 

  • The Location it is shipping from
    • 

  • The Location it is shipping to
    • 

  • The date and time the shipment occurred
    • 



The purpose of this endpoint is to create a Ship event for a container in Wholechain.




Creating a Ship Container Event


Submit an event payload containing:


    

  • The event information
    • 

  • The Location the container is shipping from
    • 

  • The Location the container is shipping to
    • 

  • The container identifier
    • 

  • The date and time of the shipment
    • 



Wholechain uses Container.Id to identify the container being shipped.


Use the Required column in the tables below to determine which fields must be provided.




Event Object


Column NameData TypeDescriptionRequired
$typeSTRINGDefines the event type. Use ship.Yes
IdSTRINGUnique identifier for the Ship event.Yes
PurchaseOrderSTRINGPurchase order associated with the shipment.No
InvoiceNumberSTRINGInvoice number associated with the shipment.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


Every Ship Container event must identify the Location where the container is shipping from.


Column NameData TypeDescriptionRequired
ShipFromLocation.IdSTRINGUnique identifier for the Location the container is shipping from.Yes


Example


"ShipFromLocation": {
  "Id": "processing_000"
}



The Ship From Location is the Location where the container exists before the shipment is processed.




Ship To Location


Every Ship Container event must identify the destination Location.


The destination can be:


    

  • Another Location within your own business
    • 

  • A Location belonging to an external Trade Partner
    • 



Column NameData TypeDescriptionRequired
ShipToLocation.IdSTRINGUnique identifier for the destination Location.Yes
ShipToLocation.DetailsOBJECTInformation used to create the destination Location if it does not already exist.Yes, if the Location does not exist


Existing Destination Location


If the destination Location already exists in Wholechain, only its Id needs to be supplied:


"ShipToLocation": {
  "Id": "warehouse_002"
}



Creating a Destination Location


If the supplied ShipToLocation.Id does not exist, include the Details object.


Wholechain uses this information to create the destination Location before processing the Ship Container event.


"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
      }
    }
  }
}



The same structure can be used when the destination is another Location within your business.




Trade Partner


Every Location belongs to a Trade Partner.


Column NameData TypeDescriptionRequired
TradePartnerOBJECTTrade Partner associated with the destination Location.Yes, if creating the Location
TradePartner.IdSTRINGUnique identifier for the Trade Partner.Yes, if creating the Trade Partner
TradePartner.NameSTRINGName of the Trade Partner.Yes, if creating the Trade Partner
TradePartner.ConnectionTypeSTRINGRelationship to the Trade Partner, such as SELF, SUPPLIER, BUYER, or OTHER.Yes, if creating the Trade Partner
TradePartner.DunsSTRINGDUNS number associated with the Trade Partner.No


If the Trade Partner already exists in Wholechain, reference its existing ID.


If it does not exist, Wholechain creates it from the supplied information before creating the Location.


Internal Shipment


For a shipment between Locations within your business, use:


"ConnectionType": "SELF"



External Shipment


For a shipment to an external customer or buyer, use:


"ConnectionType": "BUYER"





Location Information


Column NameData TypeDescriptionRequired
NameSTRINGName of the Location.Yes, if creating the Location
GlnSTRINGGlobal Location Number.No
ExtensionSTRINGAdditional Location information.No
DunsPlus4STRINGDUNS Plus 4 identifier, when applicable.No
ContactInformationOBJECTContact information associated with the Location.No
ContactInformation.NameSTRINGName of the contact person.No
ContactInformation.PhoneSTRINGPhone number of the contact person.No
ContactInformation.EmailSTRINGEmail address of the contact person.No




Address


Column NameData TypeDescriptionRequired
AddressOBJECTAddress information for the Location.Yes, if creating the Location
Address.CitySTRINGCity where the Location is situated.No
Address.StateSTRINGState or region where the Location is situated.No
Address.CountrySTRINGCountry of the Location.Yes, if creating the Location
Address.AddressLine1STRINGPrimary address line.Yes, if creating the Location
Address.AddressLine2STRINGSecondary address line.No
Address.PostalCodeSTRINGPostal code.No
Address.GeoCoordinatesOBJECTGeographical coordinates.No
Address.GeoCoordinates.LatitudeDECIMALLatitude of the Location.No
Address.GeoCoordinates.LongitudeDECIMALLongitude of the Location.No




Container


The Container object identifies the container being shipped.


Column NameData TypeDescriptionRequired
ContainerOBJECTContainer being shipped.Yes
Container.IdSTRINGUnique identifier for the container.Yes


Example


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



The container must already exist in Wholechain before it can be shipped.




Complete Request Example


The following example ships a container from an existing source Location to an external buyer Location.


If the destination Location or Trade Partner does not exist, Wholechain creates it from the supplied details.


{
  "Events": [
    {
      "$type": "ship",
      "ShipFromLocation": {
        "Id": "processing_000"
      },
      "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
            }
          }
        }
      },
      "Container": {
        "Id": "123456"
      },
      "Id": "0004",
      "PurchaseOrder": "1990091",
      "InvoiceNumber": "12314154",
      "EventTime": "2024-03-30T16:00:00",
      "EventTimeZone": "-05:00",
      "CustomProperties": [
        {
          "Name": "expiry_date",
          "Namespace": "TEST",
          "Value": "2024-03-30",
          "PropertyLocation": "ILMD"
        }
      ],
      "CertificationList": [
        {
          "Type": "urn:gdst:certType:harvestCoC",
          "Standard": "MSC Chain of Custody",
          "Agency": "MSC",
          "Value": "NO",
          "Identification": "NA"
        },
        {
          "Type": "urn:gdst:certType:fishingAuth",
          "Standard": "Los Angeles Fishing Authorization",
          "Agency": "Los Angeles Fishing Authorization",
          "Value": "",
          "Identification": ""
        },
        {
          "Type": "urn:gdst:certType:humanPolicy",
          "Standard": "WHO Human Decency Policy",
          "Agency": "WHO",
          "Value": "",
          "Identification": ""
        }
      ]
    }
  ]
}





Internal and External Container Shipments


Internal Shipment


Warehouse A → Warehouse B



Both Locations belong to your business.


External Shipment


Your Location → Buyer Location



The Ship From Location belongs to your business, and the Ship To Location belongs to the external Trade Partner.




How Wholechain Processes the Event


When a Ship Container event is submitted, Wholechain:


    

  1. Identifies the Ship From Location.
    2. 

  2. Identifies the Ship To Location.
    3. 

  3. Creates the Ship To Location and Trade Partner when they do not already exist and the required details are supplied.
    4. 

  4. Identifies the container using Container.Id.
    5. 

  5. Creates the Ship event and records the container's movement to the Ship To Location.
    6. 





Important Notes


    

  • Use $type: "ship" when shipping a container.
    • 

  • ShipFromLocation.Id identifies where the container is shipping from.
    • 

  • ShipToLocation.Id identifies where the container is shipping to.
    • 

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

  • PurchaseOrder and InvoiceNumber are optional.
    • 

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

Was this page helpful?