Receive

Endpoint

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

Sandbox URL

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

Method

POST

Endpoint: Receive Product

This endpoint is used to log a "Receive" event when a product arrives at a specified destination, creating a new product entry in the inventory. The "Receive" event is considered the starting point in the traceability lifecycle within the Wholechain platform.

Introduction

Receive events represent when you confirm a product's arrival at your own internal location. Receive events normally follow Ship events, though you can log a Receive event from a non-Wholechain user, thereby starting the traceability journey in Wholechain at this point. If the user receiving product notices any discrepancies between the ship record and the physical product received, they also have the option to reject the record, which sends a notification to the shipper that some information was off and the event needs to be revised.

How it works

Scenario 1: A user goes to their Shipping / Receiving page and clicks on the Pending tab. The user selects items that they wish to receive, and confirms it to a specific internal location.
Scenario 2: A user goes to the Shipping / Receiving page or any product's Current Inventory page and clicks Actions > Receive. This prompts them to select from whom the product came as well as the item details they are receiving. This scenario occurs when the goods come from a user who is not yet on Wholechain, or who did not use Wholechain to log a ship event.
In Scenario 1 above, the recipient also has the option to reject the items in their Pending tab if the Ship event record appears inaccurate.
Scenario 3: This action can be performed through the API

Local image

Practical Examples

A distributor confirms receipt of the product and records shipped to them from a supplier.
A grocery store confirms receipt of a shipment of fresh produce from a local farm, logging the arrival of the vegetables into their Wholechain system.

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

Header	Description	Example Value
`X-API-KEY`	Your API key	`733e286e-c578-461d-afc6-bd82efe4e6bb`
`Content-Type`	Content type of the request	`application/json`
`accept`	Response content type	`/`

Request Body Parameters

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 Requests

PythonC#Curl

import requests

url = 'https://connect.wholechain.com/Integration/JSON'
headers = {
    'accept': '*/*',
    'X-API-KEY': '733e286e-c578-461d-afc6-bd82efe4e6bb',
    'Content-Type': 'application/json'
}
data = {
    "Events": [
        {
            "$type": "receive",
            "OriginLocation": {
                "Urn": "urn:gdst:wholechain.com:location:loc:brunosfishsupply.fishingarea",
                "TradePartnerUrn": "urn:gdst:wholechain.com:party:brunosfishsupply.0",
                "Name": "Fishing Area",
                "Gln": "",
                "Address": {
                    "City": "Paranagua",
                    "State": "Parana",
                    "Country": "Brazil",
                    "AddressLine1": "R. Quarenta e Oito, 370",
                    "AddressLine2": "",
                    "PostalCode": "83210357",
                    "GeoCoordinates": {
                        "Latitude": 0,
                        "Longitude": 0
                    }
                }
            },
            "DestinationLocation": {
                "Urn": "urn:gdst:wholechain.com:location:loc:brunosfishimports.mainwarehouse",
                "TradePartnerUrn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
                "Name": "Bruno's Fish Imports",
                "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
                    }
                }
            },
            "OriginTradePartner": {
                "Urn": "urn:gdst:wholechain.com:party:brunosfishsupply.0",
                "TradePartnerId": None,
                "Name": "Bruno's Fish Supply",
                "Pgln": "",
                "ConnectionType": "SELF"
            },
            "DestinationTradePartner": {
                "Urn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
                "TradePartnerId": None,
                "Name": "Bruno's Fish Imports",
                "Pgln": "",
                "ConnectionType": "SELF"
            },
            "ContainerIdentifiers": [],
            "ProductInstances": [
                {
                    "Quantity": 3000,
                    "LotSerial": "1288888576",
                    "Urn": "urn:gdst:wholechain.com:product:lot:class:brunosfishimports.salmonwhole.1288888576",
                    "UOM": 1,
                    "ParentProduct": {
                        "Urn": "urn:gdst:wholechain.com:product:class:brunosfishimports.salmonwhole",
                        "Name": "Salmon Whole",
                        "SimpleUnitOfMeasurement": "Lbs",
                        "UnitQuantity": 0,
                        "SharingPolicy": "Open",
                        "ProductIdentifierType": "Lot",
                        "UnitDescriptor": None,
                        "Gtin": "",
                        "ProductMasterData": []
                    },
                    "TradePartnerName": "Bruno's Fish Imports",
                    "IdentifierType": "Lot"
                }
            ],
            "ExternalEventId": "003",
            "PurchaseOrder": None,
            "InvoiceNumber": "",
            "BizStep": "urn:epcglobal:cbv:bizstep:receiving",
            "ReadPoint": None,
            "Disposition": "urn:epcglobal:cbv:disp:in_progress",
            "EventTime": "2024-02-14T11:00:00+00:00",
            "EventTimeZone": "-05:00",
            "RecordTime": "2024-08-11T19:32:26.4153197+00:00",
            "TradePartner": {
                "Urn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
                "TradePartnerId": None,
                "Name": "Bruno's Fish Imports",
                "Pgln": "",
                "ConnectionType": "SELF"
            },
            "CustomProperties": [],
            "VesselCatchInformation": None,
            "CertificationList": []
        }
    ]
}

response = requests.post(url, headers=headers, json=data)

print(response.status_code)
print(response.json())

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace WholechainAPI
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // Define the URL
            var url = "https://connect.wholechain.com/Integration/JSON";

            // Define the JSON payload
            var jsonData = @"{
                ""Events"": [
                    {
                        ""$type"": ""receive"",
                        ""OriginLocation"": {
                            ""Urn"": ""urn:gdst:wholechain.com:location:loc:brunosfishsupply.fishingarea"",
                            ""TradePartnerUrn"": ""urn:gdst:wholechain.com:party:brunosfishsupply.0"",
                            ""Name"": ""Fishing Area"",
                            ""Gln"": """",
                            ""Address"": {
                                ""City"": ""Paranagua"",
                                ""State"": ""Parana"",
                                ""Country"": ""Brazil"",
                                ""AddressLine1"": ""R. Quarenta e Oito, 370"",
                                ""AddressLine2"": """",
                                ""PostalCode"": ""83210357"",
                                ""GeoCoordinates"": {
                                    ""Latitude"": 0,
                                    ""Longitude"": 0
                                }
                            }
                        },
                        ""DestinationLocation"": {
                            ""Urn"": ""urn:gdst:wholechain.com:location:loc:brunosfishimports.mainwarehouse"",
                            ""TradePartnerUrn"": ""urn:gdst:wholechain.com:party:brunosfishimports.0"",
                            ""Name"": ""Bruno's Fish Imports"",
                            ""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
                                }
                            }
                        },
                        ""OriginTradePartner"": {
                            ""Urn"": ""urn:gdst:wholechain.com:party:brunosfishsupply.0"",
                            ""TradePartnerId"": null,
                            ""Name"": ""Bruno's Fish Supply"",
                            ""Pgln"": """",
                            ""ConnectionType"": ""SELF""
                        },
                        ""DestinationTradePartner"": {
                            ""Urn"": ""urn:gdst:wholechain.com:party:brunosfishimports.0"",
                            ""TradePartnerId"": null,
                            ""Name"": ""Bruno's Fish Imports"",
                            ""Pgln"": """",
                            ""ConnectionType"": ""SELF""
                        },
                        ""ContainerIdentifiers"": [],
                        ""ProductInstances"": [
                            {
                                ""Quantity"": 3000,
                                ""LotSerial"": ""1288888576"",
                                ""Urn"": ""urn:gdst:wholechain.com:product:lot:class:brunosfishimports.salmonwhole.1288888576"",
                                ""UOM"": 1,
                                ""ParentProduct"": {
                                    ""Urn"": ""urn:gdst:wholechain.com:product:class:brunosfishimports.salmonwhole"",
                                    ""Name"": ""Salmon Whole"",
                                    ""SimpleUnitOfMeasurement"": ""Lbs"",
                                    ""UnitQuantity"": 0,
                                    ""SharingPolicy"": ""Open"",
                                    ""ProductIdentifierType"": ""Lot"",
                                    ""UnitDescriptor"": null,
                                    ""Gtin"": """",
                                    ""ProductMasterData"": []
                                },
                                ""TradePartnerName"": ""Bruno's Fish Imports"",
                                ""IdentifierType"": ""Lot""
                            }
                        ],
                        ""ExternalEventId"": ""003"",
                        ""PurchaseOrder"": null,
                        ""InvoiceNumber"": """",
                        ""BizStep"": ""urn:epcglobal:cbv:bizstep:receiving"",
                        ""ReadPoint"": null,
                        ""Disposition"": ""urn:epcglobal:cbv:disp:in_progress"",
                        ""EventTime"": ""2024-02-14T11:00:00+00:00"",
                        ""EventTimeZone"": ""-05:00"",
                        ""RecordTime"": ""2024-08-11T19:32:26.4153197+00:00"",
                        ""TradePartner"": {
                            ""Urn"": ""urn:gdst:wholechain.com:party:brunosfishimports.0"",
                            ""TradePartnerId"": null,
                            ""Name"": ""Bruno's Fish Imports"",
                            ""Pgln"": """",
                            ""ConnectionType"": ""SELF""
                        },
                        ""CustomProperties"": [],
                        ""VesselCatchInformation"": null,
                        ""CertificationList"": []
                    }
                ]
            }";

            // Create HttpClient
            using (var client = new HttpClient())
            {
                // Set the headers
                client.DefaultRequestHeaders.Accept.Clear();
                client.DefaultRequestHeaders.Add("accept", "*/*");
                client.DefaultRequestHeaders.Add("X-API-KEY", "633e266d-c578-461d-afc6-bd82efe4e6bb");

                // Create the content for the request
                var content = new StringContent(jsonData, Encoding.UTF8, "application/json");

                // Make the POST request
                HttpResponseMessage response = await client.PostAsync(url, content);

                // Print the status code
                Console.WriteLine("Status Code: " + response.StatusCode);

                // Print the response content
                if (response.IsSuccessStatusCode)
                {
                    string responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine("Response: " + responseBody);
                }
                else
                {
                    Console.WriteLine("Request failed with status code: " + response.StatusCode);
                }
            }
        }
    }
}

curl -X POST 'https://connect.wholechain.com/Integration/JSON' \
-H 'accept: */*' \
-H 'X-API-KEY: 633e266d-c578-461d-afc6-bd82efe4e6bb' \
-H 'Content-Type: application/json' \
-d '{
    "Events": [
        {
            "$type": "receive",
            "OriginLocation": {
                "Urn": "urn:gdst:wholechain.com:location:loc:brunosfishsupply.fishingarea",
                "TradePartnerUrn": "urn:gdst:wholechain.com:party:brunosfishsupply.0",
                "Name": "Fishing Area",
                "Gln": "",
                "Address": {
                    "City": "Paranagua",
                    "State": "Parana",
                    "Country": "Brazil",
                    "AddressLine1": "R. Quarenta e Oito, 370",
                    "AddressLine2": "",
                    "PostalCode": "83210357",
                    "GeoCoordinates": {
                        "Latitude": 0,
                        "Longitude": 0
                    }
                }
            },
            "DestinationLocation": {
                "Urn": "urn:gdst:wholechain.com:location:loc:brunosfishimports.mainwarehouse",
                "TradePartnerUrn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
                "Name": "Bruno'\''s Fish Imports",
                "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
                    }
                }
            },
            "OriginTradePartner": {
                "Urn": "urn:gdst:wholechain.com:party:brunosfishsupply.0",
                "TradePartnerId": null,
                "Name": "Bruno'\''s Fish Supply",
                "Pgln": "",
                "ConnectionType": "SELF"
            },
            "DestinationTradePartner": {
                "Urn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
                "TradePartnerId": null,
                "Name": "Bruno'\''s Fish Imports",
                "Pgln": "",
                "ConnectionType": "SELF"
            },
            "ContainerIdentifiers": [],
            "ProductInstances": [
                {
                    "Quantity": 3000,
                    "LotSerial": "1288888576",
                    "Urn": "urn:gdst:wholechain.com:product:lot:class:brunosfishimports.salmonwhole.1288888576",
                    "UOM": 1,
                    "ParentProduct": {
                        "Urn": "urn:gdst:wholechain.com:product:class:brunosfishimports.salmonwhole",
                        "Name": "Salmon Whole",
                        "SimpleUnitOfMeasurement": "Lbs",
                        "UnitQuantity": 0,
                        "SharingPolicy": "Open",
                        "ProductIdentifierType": "Lot",
                        "UnitDescriptor": null,
                        "Gtin": "",
                        "ProductMasterData": []
                    },
                    "TradePartnerName": "Bruno'\''s Fish Imports",
                    "IdentifierType": "Lot"
                }
            ],
            "ExternalEventId": "003",
            "PurchaseOrder": null,
            "InvoiceNumber": "",
            "BizStep": "urn:epcglobal:cbv:bizstep:receiving",
            "ReadPoint": null,
            "Disposition": "urn:epcglobal:cbv:disp:in_progress",
            "EventTime": "2024-02-14T11:00:00+00:00",
            "EventTimeZone": "-05:00",
            "RecordTime": "2024-08-11T19:32:26.4153197+00:00",
            "TradePartner": {
                "Urn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
                "TradePartnerId": null,
                "Name": "Bruno'\''s Fish Imports",
                "Pgln": "",
                "ConnectionType": "SELF"
            },
            "CustomProperties": [],
            "VesselCatchInformation": null,
            "CertificationList": []
        }
    ]
}'

Example Response

200
{'result': 'Success', 'message': None, 'errors': []}