Skip to content

External Ship

Endpoint URL

https://connect.wholechain.com/Integration/JSON

Sandbox URL

https://connect-sandbox.wholechain.com/Integration/JSON

Method:

POST

Introduction

External Ship events represent when product is shipped from one Company to another. Logging a Ship event moves product item(s) from a company's current inventory to its shipped inventory tab with the status "pending", until the recipient company either receives or rejects the item(s) in their account.

How it works:

  • Option 1: a Wholechain user selects an item from their current inventory, and selects the recipient company + location as well as dispatch date.
  • Option 2: a Wholechain user creates a Batch Ship event from the Shipping / Receiving page, where they can send multiple products and items at once.
  • Option 3: The user can perform this action through the API Local image

Practical Examples

  • A shrimp processor ships 3 pallets of shrimp to a distributor’s warehouse.
  • A winery ships 500 bottles of wine to a retailer's distribution center.

Authentication

To use this API, you must include the API key in the request header. The API key is assigned to your account and ensures secure communication with the Wholechain platform.

Request Headers

Header Description Example Value
X-API-KEY Your API key YOUR_API_KEY_HERE
Content-Type Content type of the request application/json
accept Response content type */*

Request Body Parameters:

The following table outlines the required input variables for the ship event.

Location Object

Column Name Data Type Description
Urn STRING Unique identifier for the location.
TradePartnerUrn STRING Trade Partner URN associated with the location.
Name STRING Name of the location.
Gln STRING Global Location Number (GLN), if available.
City STRING City where the location is based.
State STRING State or province.
Country STRING Country.
AddressLine1 STRING First line of the address.
AddressLine2 STRING Second line of the address (optional).
PostalCode STRING Postal or ZIP code.
Latitude FLOAT Geographic latitude of the location.
Longitude FLOAT Geographic longitude of the location.

TradePartner Object

Column Name Data Type Description
Urn STRING Unique identifier for the trade partner.
TradePartnerId STRING Unique ID for the trade partner (optional).
Name STRING Name of the trade partner.
Pgln STRING Party GLN (Global Location Number).
ConnectionType STRING Type of connection (e.g., SELF).

ProductInstances Object

Column Name Data Type Description
Quantity FLOAT Quantity of the product in this instance.
LotSerial STRING Lot or serial number of the product.
Urn STRING Unique identifier for the product instance.
UOM STRING Unit of measurement (e.g., Lbs).
Gtin STRING Global Trade Item Number (optional).
ParentProductUrn STRING URN of the parent product.
ParentProductName STRING Name of the parent product.
SimpleUOM STRING Simplified unit of measurement.
SharingPolicy STRING Product sharing policy (e.g., Open).
ProductIdentifierType STRING Identifier type (e.g., Lot).

ProductMasterData Object

Column Name Data Type Description
ParentProductUrn STRING URN of the parent product this data is associated with.
Name STRING Name of the product attribute.
Namespace STRING Namespace of the attribute (e.g., cbvmda).
Value STRING Value of the product attribute.
ElementId STRING Element ID for the attribute.

Event Object

Column Name Data Type Description
ExternalEventId STRING This must be different for every API call
PurchaseOrder STRING Purchase order number.
InvoiceNumber STRING Invoice number associated with the event.
BizStep STRING Business step identifier.
Disposition STRING Disposition of the product in the event.
EventTime DATETIME Timestamp for when the event occurred.
EventTimeZone STRING Time zone offset for the event.
RecordTime DATETIME Timestamp for when the event was recorded.

CustomProperties Object

Column Name Data Type Description
EventId STRING ID of the event this property is associated with.
Name STRING Name of the custom property.
Namespace STRING Namespace of the property.
Value STRING Value of the custom property.
PropertyLocation STRING Location of the property (e.g., ILMD).

CertificationList Object

Column Name Data Type Description
EventId STRING ID of the event this certification is linked to.
CertificationType STRING Type of certification (e.g., harvestCoC).
CertificationStandard STRING Certification standard (e.g., MSC Chain of Custody).
CertificationAgency STRING Agency providing the certification.
CertificationValue STRING Certification value.
CertificationIdentification STRING Certification identification number or code.

Example Request

import requests
url = 'https://connect.wholechain.com/Integration/JSON'
headers = {
    'accept': '*/*',
    'X-API-KEY': 'e163a6b0-5e65-4b4c-8384-2c9867819569',
    'Content-Type': 'application/json'
}
data = {
    "Events": [
        {
            "$type": "ship",
            "OriginLocation": {
                "Urn": "urn:gdst:wholechain.com:location:loc:brunosfishimports.mainwarehouse",
                "TradePartnerUrn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
                "Name": "Main Warehouse",
                "Gln": "",
                "Address": {
                    "City": "Curitiba",
                    "State": "Parana",
                    "Country": "Brazil",
                    "AddressLine1": "Av Presidente Wenceslau Braz, 1893",
                    "AddressLine2": "T2AP65",
                    "PostalCode": "81010001",
                    "GeoCoordinates": {
                        "Latitude": -25.441105,
                        "Longitude": -49.276855
                    }
                }
            },
            "DestinationLocation": {
                "Urn": "urn:gdst:wholechain.com:location:loc:integrationreceiver.receiverlocation",
                "TradePartnerUrn": "urn:gdst:wholechain.com:party:integrationreceiver.0",
                "Name": "Receiver Location",
                "Address": {
                    "GeoCoordinates": {
                        "Latitude": 1,
                        "Longitude": 1
                    }
                }
            },
            "OriginTradePartner": {
                "Urn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
                "TradePartnerId": None,
                "Name": "Bruno's Fish Imports",
                "Pgln": "",
                "ConnectionType": "SELF"
            },
            "DestinationTradePartner": {
                "Urn": "urn:gdst:wholechain.com:party:integrationreceiver.0",
                "Name": "Integration Receiver"
            },
            "ProductInstances": [
                {
                    "Quantity": 25,
                    "LotSerial": "12345",
                    "Urn": "urn:gdst:wholechain.com:product:lot:class:brunosfishimports.hake.12345",
                    "UOM": "Lbs",
                    "Gtin": "",
                    "ParentProduct": {
                        "Urn": "urn:gdst:wholechain.com:product:class:brunosfishimports.hake",
                        "Name": "Hake",
                        "SimpleUnitOfMeasurement": "Lbs",
                        "SharingPolicy": "Open",
                        "ProductIdentifierType": "Lot",
                        "ProductMasterData": [
                            {
                                "Name": "Species For Fishery Statistics Purposes Name",
                                "Namespace": "cbvmda",
                                "Value": "Salmo salar",
                                "ElementId": "speciesForFisheryStatisticsPurposesName"
                            },
                            {
                                "Name": "Trade Item Condition Code",
                                "Namespace": "cbvmda",
                                "Value": "RESPONSIBLY FARMED",
                                "ElementId": "tradeItemConditionCode"
                            }
                        ]
                    },
                    "TradePartnerName": "Bruno's Fish Imports"
                }
            ],
            "ExternalEventId": "0002",
            "PurchaseOrder": "1990091",
            "InvoiceNumber": "12314154",
            "BizStep": "urn:epcglobal:cbv:bizstep:shipping",
            "Disposition": "urn:epcglobal:cbv:disp:in_transit",
            "EventTime": "2024-03-30T13:00:00+00:00",
            "EventTimeZone": "-05:00",
            "RecordTime": "2024-08-11T19:32:26.4137461+00:00",
            "TradePartner": {
                "Urn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
                "TradePartnerId": None,
                "Name": "Bruno's Fish Imports",
                "Pgln": "",
                "ConnectionType": "SELF"
            },
            "CustomProperties": [
                {
                    "Name": "expiry_date",
                    "Namespace": "",
                    "Value": "2024-03-30",
                    "PropertyLocation": "ILMD"
                }
            ],
            "CertificationList": [
                {
                    "CertificationType": "urn:gdst:certType:harvestCoC",
                    "CertificationStandard": "MSC Chain of Custody",
                    "CertificationAgency": "MSC",
                    "CertificationValue": "NO",
                    "CertificationIdentification": "NA"
                },
                {
                    "CertificationType": "urn:gdst:certType:fishingAuth",
                    "CertificationStandard": "Los Angeles Fishing Authorization",
                    "CertificationAgency": "Los Angeles Fishing Authorization",
                    "CertificationValue": "",
                    "CertificationIdentification": ""
                },
                {
                    "CertificationType": "urn:gdst:certType:humanPolicy",
                    "CertificationStandard": "WHO Human Decency Policy",
                    "CertificationAgency": "WHO",
                    "CertificationValue": "",
                    "CertificationIdentification": ""
                }
            ]
        }
    ]
}
response = requests.post(url, headers=headers, json=data)

print(response.status_code)
print(response.json())
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

class Program
{
    static async Task Main(string[] args)
    {
        // Define the URL and headers
        string url = "https://connect.wholechain.com/Integration/JSON";
        string apiKey = "e163a6b0-5e65-4b4c-8384-2c9867819569";

        // Create the HTTP client and set the request headers
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("*/*"));
            client.DefaultRequestHeaders.Add("X-API-KEY", apiKey);
            client.DefaultRequestHeaders.Add("Content-Type", "application/json");

            // Define the JSON data payload
            var data = new
            {
                Events = new[]
                {
                    new
                    {
                        _type = "ship",
                        OriginLocation = new
                        {
                            Urn = "urn:gdst:wholechain.com:location:loc:brunosfishimports.mainwarehouse",
                            TradePartnerUrn = "urn:gdst:wholechain.com:party:brunosfishimports.0",
                            Name = "Main Warehouse",
                            Gln = "",
                            Address = new
                            {
                                City = "Curitiba",
                                State = "Parana",
                                Country = "Brazil",
                                AddressLine1 = "Av Presidente Wenceslau Braz, 1893",
                                AddressLine2 = "T2AP65",
                                PostalCode = "81010001",
                                GeoCoordinates = new
                                {
                                    Latitude = -25.441105,
                                    Longitude = -49.276855
                                }
                            }
                        },
                        DestinationLocation = new
                        {
                            Urn = "urn:gdst:wholechain.com:location:loc:integrationreceiver.receiverlocation",
                            TradePartnerUrn = "urn:gdst:wholechain.com:party:integrationreceiver.0",
                            Name = "Receiver Location",
                            Address = new
                            {
                                GeoCoordinates = new
                                {
                                    Latitude = 1,
                                    Longitude = 1
                                }
                            }
                        },
                        OriginTradePartner = new
                        {
                            Urn = "urn:gdst:wholechain.com:party:brunosfishimports.0",
                            TradePartnerId = (string)null,
                            Name = "Bruno's Fish Imports",
                            Pgln = "",
                            ConnectionType = "SELF"
                        },
                        DestinationTradePartner = new
                        {
                            Urn = "urn:gdst:wholechain.com:party:integrationreceiver.0",
                            Name = "Integration Receiver"
                        },
                        ProductInstances = new[]
                        {
                            new
                            {
                                Quantity = 25,
                                LotSerial = "12345",
                                Urn = "urn:gdst:wholechain.com:product:lot:class:brunosfishimports.hake.12345",
                                UOM = "Lbs",
                                Gtin = "",
                                ParentProduct = new
                                {
                                    Urn = "urn:gdst:wholechain.com:product:class:brunosfishimports.hake",
                                    Name = "Hake",
                                    SimpleUnitOfMeasurement = "Lbs",
                                    SharingPolicy = "Open",
                                    ProductIdentifierType = "Lot",
                                    ProductMasterData = new[]
                                    {
                                        new { Name = "Species For Fishery Statistics Purposes Name", Namespace = "cbvmda", Value = "Salmo salar", ElementId = "speciesForFisheryStatisticsPurposesName" },
                                        new { Name = "Trade Item Condition Code", Namespace = "cbvmda", Value = "RESPONSIBLY FARMED", ElementId = "tradeItemConditionCode" }
                                    }
                                },
                                TradePartnerName = "Bruno's Fish Imports"
                            }
                        },
                        ExternalEventId = "0002",
                        PurchaseOrder = "1990091",
                        InvoiceNumber = "12314154",
                        BizStep = "urn:epcglobal:cbv:bizstep:shipping",
                        Disposition = "urn:epcglobal:cbv:disp:in_transit",
                        EventTime = "2024-03-30T13:00:00+00:00",
                        EventTimeZone = "-05:00",
                        RecordTime = "2024-08-11T19:32:26.4137461+00:00",
                        TradePartner = new
                        {
                            Urn = "urn:gdst:wholechain.com:party:brunosfishimports.0",
                            TradePartnerId = (string)null,
                            Name = "Bruno's Fish Imports",
                            Pgln = "",
                            ConnectionType = "SELF"
                        },
                        CustomProperties = new[]
                        {
                            new { Name = "expiry_date", Namespace = "", Value = "2024-03-30", PropertyLocation = "ILMD" }
                        },
                        CertificationList = new[]
                        {
                            new { CertificationType = "urn:gdst:certType:harvestCoC", CertificationStandard = "MSC Chain of Custody", CertificationAgency = "MSC", CertificationValue = "NO", CertificationIdentification = "NA" },
                            new { CertificationType = "urn:gdst:certType:fishingAuth", CertificationStandard = "Los Angeles Fishing Authorization", CertificationAgency = "Los Angeles Fishing Authorization", CertificationValue = "", CertificationIdentification = "" },
                            new { CertificationType = "urn:gdst:certType:humanPolicy", CertificationStandard = "WHO Human Decency Policy", CertificationAgency = "WHO", CertificationValue = "", CertificationIdentification = "" }
                        }
                    }
                }
            };

            // Convert the data object to JSON
            var jsonData = JsonConvert.SerializeObject(data);

            // Make the POST request
            HttpResponseMessage response = await client.PostAsync(url, new StringContent(jsonData, Encoding.UTF8, "application/json"));

            // Print the response status code and body
            Console.WriteLine($"Response Status Code: {response.StatusCode}");
            Console.WriteLine($"Response Body: {await response.Content.ReadAsStringAsync()}");
        }
    }
}
curl -X POST 'https://connect.wholechain.com/Integration/JSON' \
-H 'accept: */*' \
-H 'X-API-KEY: e163a6b0-5e65-4b4c-8384-2c9867819569' \
-H 'Content-Type: application/json' \
-d '{
"Events": [
    {
    "$type": "ship",
    "OriginLocation": {
        "Urn": "urn:gdst:wholechain.com:location:loc:brunosfishimports.mainwarehouse",
        "TradePartnerUrn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
        "Name": "Main Warehouse",
        "Gln": "",
        "Address": {
        "City": "Curitiba",
        "State": "Parana",
        "Country": "Brazil",
        "AddressLine1": "Av Presidente Wenceslau Braz, 1893",
        "AddressLine2": "T2AP65",
        "PostalCode": "81010001",
        "GeoCoordinates": {
            "Latitude": -25.441105,
            "Longitude": -49.276855
        }
        }
    },
    "DestinationLocation": {
        "Urn": "urn:gdst:wholechain.com:location:loc:integrationreceiver.receiverlocation",
        "TradePartnerUrn": "urn:gdst:wholechain.com:party:integrationreceiver.0",
        "Name": "Receiver Location",
        "Address": {
        "GeoCoordinates": {
            "Latitude": 1,
            "Longitude": 1
        }
        }
    },
    "OriginTradePartner": {
        "Urn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
        "TradePartnerId": null,
        "Name": "Bruno'\''s Fish Imports",
        "Pgln": "",
        "ConnectionType": "SELF"
    },
    "DestinationTradePartner": {
        "Urn": "urn:gdst:wholechain.com:party:integrationreceiver.0",
        "Name": "Integration Receiver"
    },
    "ProductInstances": [
        {
        "Quantity": 25,
        "LotSerial": "12345",
        "Urn": "urn:gdst:wholechain.com:product:lot:class:brunosfishimports.hake.12345",
        "UOM": "Lbs",
        "Gtin": "",
        "ParentProduct": {
            "Urn": "urn:gdst:wholechain.com:product:class:brunosfishimports.hake",
            "Name": "Hake",
            "SimpleUnitOfMeasurement": "Lbs",
            "SharingPolicy": "Open",
            "ProductIdentifierType": "Lot",
            "ProductMasterData": [
            {
                "Name": "Species For Fishery Statistics Purposes Name",
                "Namespace": "cbvmda",
                "Value": "Salmo salar",
                "ElementId": "speciesForFisheryStatisticsPurposesName"
            },
            {
                "Name": "Trade Item Condition Code",
                "Namespace": "cbvmda",
                "Value": "RESPONSIBLY FARMED",
                "ElementId": "tradeItemConditionCode"
            }
            ]
        },
        "TradePartnerName": "Bruno'\''s Fish Imports"
        }
    ],
    "ExternalEventId": "0002",
    "PurchaseOrder": "1990091",
    "InvoiceNumber": "12314154",
    "BizStep": "urn:epcglobal:cbv:bizstep:shipping",
    "Disposition": "urn:epcglobal:cbv:disp:in_transit",
    "EventTime": "2024-03-30T13:00:00+00:00",
    "EventTimeZone": "-05:00",
    "RecordTime": "2024-08-11T19:32:26.4137461+00:00",
    "TradePartner": {
        "Urn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
        "TradePartnerId": null,
        "Name": "Bruno'\''s Fish Imports",
        "Pgln": "",
        "ConnectionType": "SELF"
    },
    "CustomProperties": [
        {
        "Name": "expiry_date",
        "Namespace": "",
        "Value": "2024-03-30",
        "PropertyLocation": "ILMD"
        }
    ],
    "CertificationList": [
        {
        "CertificationType": "urn:gdst:certType:harvestCoC",
        "CertificationStandard": "MSC Chain of Custody",
        "CertificationAgency": "MSC",
        "CertificationValue": "NO",
        "CertificationIdentification": "NA"
        },
        {
        "CertificationType": "urn:gdst:certType:fishingAuth",
        "CertificationStandard": "Los Angeles Fishing Authorization",
        "CertificationAgency": "Los Angeles Fishing Authorization",
        "CertificationValue": "",
        "CertificationIdentification": ""
        },
        {
        "CertificationType": "urn:gdst:certType:humanPolicy",
        "CertificationStandard": "WHO Human Decency Policy",
        "CertificationAgency": "WHO",
        "CertificationValue": "",
        "CertificationIdentification": ""
        }
    ]
    }
]
}'

Response

The following response is returned when a request is successfully processed. The HTTP status code 200 indicates that the operation completed without major errors, and the response body includes information about the different entities that were processed.

Response Body

{
  "status": 200,
  "message": "Success",
  "result": {
    "products": [
      {
        "gtin": null,
        "status": "Skipped",
        "id": "3385e8ea-7c12-4a94-9524-3f68d1667b67",
        "name": "Hake",
        "urn": "urn:gdst:wholechain.com:product:class:brunosfishimports.hake"
      }
    ],
    "locations": [
      {
        "gln": null,
        "geoCoordinates": {
          "latitude": 13.7283667,
          "longitude": 100.5145846
        },
        "status": "Skipped",
        "id": "dabbeeae-8d4a-411c-815f-91477f50924f",
        "name": "Main Warehouse",
        "urn": "urn:gdst:wholechain.com:location:loc:brunosfishimports.mainwarehouse"
      },
      {
        "gln": null,
        "geoCoordinates": {
          "latitude": 39.3614358,
          "longitude": -74.4179374
        },
        "status": "Skipped",
        "id": "7c571ef9-f0e1-4833-a404-6621aee90245",
        "name": "US Warehouse",
        "urn": "urn:gdst:wholechain.com:location:loc:brunosfishimports.uswarehouse"
      }
    ],
    "tradePartners": [
      {
        "pgln": null,
        "status": "Skipped",
        "id": "324de292-976d-4ff8-8215-945b63e7d5d5",
        "name": "Bruno's Fish Imports",
        "urn": "urn:gdst:wholechain.com:party:brunosfishimports.0"
      },
      {
        "pgln": "",
        "status": "Skipped",
        "id": "80c2986d-97a5-4842-a3da-befadeaf19ee",
        "name": "Integration Receiver",
        "urn": "urn:gdst:wholechain.com:party:integrationreceiver.0"
      }
    ],
    "events": [
      {
        "type": "Ship",
        "eventDate": "2024-03-30T13:00:00+00:00",
        "productInstances": [
          {
            "quantity": 25,
            "lotSerial": "12345",
            "status": "Created",
            "id": "515540b3-f40a-41a0-b319-a01cd82ce198",
            "name": "Hake",
            "urn": "urn:gdst:wholechain.com:product:lot:class:brunosfishimports.hake.12345"
          }
        ],
        "status": "Created",
        "id": "6d029c02-1270-495a-ba68-2bc598003aa2",
        "name": "Ship",
        "urn": "urn:uuid:6d029c02-1270-495a-ba68-2bc598003aa2"
      }
    ]
  },
  "errors": []
}