Sharing units (listings)

Sharing units, also referred to as listings, allow a data source (typically a supplier) to share attributes dedicated to a specific data recipient (typically a retailer). A dedicated attribute can be an attribute that only exists for this specific recipient or an attribute whose value is dedicated to the recipient (ex: the net price).

As those specific attributes reflect specific conditions/content negotiated between the source and the recipient, when received, they can be accepted or rejected.

In our data model, those specific attributes are grouped in the sharingUnits element. A sharing unit has a status carrying the business decision made by the recipient (agreeing or rejecting the specific conditions/contents pushed by the source).

Structure of a sharing unit

A sharing unit is composed of the following main elements

ElementsDefintion
statusCorrespond to the business decision made by the recipient regarding the specific content/conditions contained in the sharing unit.

Possible status are the following :
DRAFT: Sharing unit has been created by the data source but not shared with the recipient.
INIT: Sharing unit has been shared by the source but no decision has been made by the recipient.
AGREED: Conditions contained in the sharing unit have been agreed by the recipient.
REJECTED : Conditions contained in the sharing unit have been rejected by the recipient.
lastRequestWhen an update is made by the data source on an agreed sharing unit the content of this update will not be automatically merged on the recipient as the recipient might want to check the update before accepting it. In this case, new version of the sharing unit can be found in the lastRequest element.
sourceOrganisationIdentifies the source organisation having created the sharing unit
recipientOrganisationIdentifies the targeted recipient organisation
dataContains the specific attributes targeted for the recipient.

Example :
* hierarchyProduct identifies the specific packaging condition proposed by the data source to deliver the product to the recipient (see Logistical hierarchies). Hierarchy is identified with the GTIN (or UUID, see uuid) of the highest logistical item.
createdAtDate when the sharing unit was created.
updatedAtDate of the last update on the sharing unit.

Example of a sharing unit

{
    "sharingUnits": [{
        "lastRequest": "",
        "status": "AGREED",
        "product": "",
        "sourceOrganization": {"nameLegal": "Delivery GS1 UK Manufacturer"},
        "answersTo": [],
        "updatedAt": "2018-01-26T11:57:57",
        "data": {
            "hierarchy": "",
            "hierarchyProduct": {"gtin": "03663836022249"},
            "campaignName": "June Range Review"
        },
        "createdAt": "2018-01-26T11:52:53"
    }]
}

Import a sharing unit using the API

As a supplier, you can import sharing units via API. JSON and XML formats are accepted but the sharing unit node must be added at a different position in the product payload depending on the format you choose.

JSON

❗️

The sharing unit node must be added in the logistical hierarchy node, at the highest level of the shared hierarchy.

Mandatory elementDefinition
codeInternal code chosen by you to identify the sharing unit
glnThe GLN code of your retailer
hierarchyProductGTIN of the shared logistical hierarchy

You can also add optional specific information linked to the sharing unit of the retailer in recipientSpecifics, such as the field minimumLifespanFromArrival.

"gtin": "00000000000001",
"logisticalHierarchies": [{
    "gtin": "00000000000002",
    "version": {
      	"gtin": "00000000000002",
      	"isConsumerUnit": false,
      	"typePackaging": {"code": "PALLET"},
      	"shareWithRecipients": [{
        			"code": "supplier internal code",
        			"recipient": {"gln": "3403825576007"},
        			"recipientSpecifics": {
          					"hierarchyProduct": {"gtin": "00000000000002"},
          					"minimumLifespanFromArrival": 123
        			}
     		}]
   	 }
}]

XML

❗️

In XML, the sharing unit node must be added in the product data, not in the logistical hierarchy.

<product>
   <gtin>00000000000001</gtin>
   <shareWithRecipients>
      <shareWithRecipient>
         <code>supplier internal code</code>
         <recipient>
            <gln>3403825576007</gln>
         </recipient>
         <recipientSpecifics>
            <hierarchyProduct>
               <gtin>00000000000002</gtin>
            </hierarchyProduct>
            <minimumLifespanFromArrival>123</minimumLifespanFromArrival>
         </recipientSpecifics>
      </shareWithRecipient>
   </shareWithRecipients>
   <logisticalHierarchies></logisticalHierarchies>
</product>