HD Workflow Interface Contracts

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Interface Contract

Changed on:

11 Feb 2025

Detailed Description

The below Interface Contracts document the interaction points with the HD workflow. These allow you to ensure that any integration made into the workflow will enable the workflow to work correctly.

OrderAppeasement Event

This event is used to create appeasement of the order.Request Payload

Property	Description	Type	Required?
appeasementAmount	The appeasement amount	String	Required
appeasementReason	The appeasement reason	String	Required
comment	The comment of appeasement	String	Optional

Event Request Example

1{
2  "name": "OrderAppeasement",
3  "accountId": "<accountId>",
4  "entityType": "ORDER",
5  "entityId": "<orderId>",
6  "entityRef": "<orderRef>",
7  "entitySubtype": "HD",
8  "rootEntityType": "ORDER",
9  "retailerId": "<retailerId>",
10  "attributes": {
11    "appeasementAmount": "<amount>",
12    "appeasementReason": "<reason>",
13    "comment": "<comment>"
14  }
15}

OrderAddressChange Event

This event is used to update the order delivery address.Request Payload

Property	Description	Type	Required?
changeReason	Reason for address change	String	Optional
deliveryAddress	The delivery address that has changed	Object	Optional

deliveryAddress Definition

Property	Description	Type	Required?	Notes
city	The city that has changed	String	Optional
companyName	The company name that has changed	String	Optional
country	The country that has changed	String	Optional
name	The name that has changed	String	Optional
postcode	The postcode that has changed	String	Optional
state	The state that has changed	String	Optional
street	The street that has changed	String	Optional

Event Request Example

1{
2  "name":"OrderAddressChange",
3  "accountId":"<accountId>",
4  "entityType":"ORDER",
5  "entityId":"<orderId>",
6  "entityRef":"<orderRef>",
7  "entitySubtype":"HD",
8  "rootEntityType":"ORDER",
9  "retailerId":"<retailerId>",
10  "attributes":{
11    "deliveryAddress":{
12      "companyName":"<company>",
13      "name":"<name>",
14      "street":"<street>",
15      "city":"<city>",
16      "postcode":"<postcode>",
17      "state":"<state>",
18      "country":"<country>"
19      },
20    "changeReason":"<reason>"
21  }
22}

OrderCancel Event

This event is used to cancel the order.Request Payload

Property	Description	Type	Required?
entityId	The order id	String	Required
entityRef	The order reference	String	Required
entitySubtype	The order type	String	Required
entityType	The type of the entity (Order)	String	Required
name	The name of the ruleSet	String	Required
retailerId	The retailer id	String	Required
attributes	The attributes	Object	Optional

Event Request Example

1{
2  "name": "OrderCancel",
3  "entityType": "ORDER",
4  "entityId": "40606",
5  "entityRef": "GAP_50::FC_50::OI_981-976-8005",
6  "entitySubtype": "HD",
7  "rootEntityType": "ORDER",
8  "retailerId": "2025",
9  "attributes": {}
10}

OrderRevision Event

This event is used to revise the order.Request Payload

Property	Description	Type	Required?
revisedItems	The list of revised items	[revisedItems]	Required

revisedItems Definition

Property	Description	Type	Required?	Notes
newQty	The new quantity of the revised order item	Integer	Optional	If newQty is null in the incoming event, the rule will grab the value from the old Order
unitPrice	The unit price of the revised order	Double	Optional	If unitPrice is null in the incoming event, the rule will grab the value from the old Order
orderItemRef	The order item reference of the revised order	String	Required
comment	The comment of the revise	String	Optional
revisionReason	The reason of the revise	RevisionReason	Required	Revision reason is only compulsory for removed or changed items

RevisionReason Type

Property	Description	Type	Required?
value	The value of the revision reason	String	Required
label	The label in i18n format	String	Required

Event Request Example

1{
2  "name":"OrderRevision",
3  "accountId":"<accountId>",
4  "entityType":"ORDER",
5  "entityId":"<orderId>",
6  "entityRef":"<orderRef>",
7  "entitySubtype":"HD",
8  "rootEntityType":"ORDER",
9  "retailerId":"<retailerId>",
10  "attributes":{
11    "revisedItems":[
12      {
13        "comment":"<comment>",
14        "newQty":1,
15        "orderItemRef":"<orderItemRef>",
16        "revisionReason":{
17          "label":"<label in i18n format>",
18          "value":"<reason_value>"
19        },
20      "unitPrice":100
21      },
22      {
23        "comment":"<comment>",
24        "newQty":2,
25        "orderItemRef":"<orderItemRef>",
26        "revisionReason":{
27          "label":"<label in i18n format>",
28          "value":"<reason_value>"
29          },
30        "unitPrice":100
31      }
32    ]
33  }
34}

WavePack Event

This event is used as an external (anything from outside this workflow) anytime finishing picking and starting packing of the order in the store is triggered.Request Payload

Property	Description	Type	Required?
pickedItems	The list of picked items	[pickedItem]	Required
fulfilmentItems	The list of fulfilment items	[fulfilmentItem]	Optional

pickedItem Definition

Property	Description	Type	Required?	Notes
GTIN	The Global Trade Item Number (GTIN) for this Product	String	Optional
availableQty	The available quantity of order item	float	Required	availableQty should be positive
catalogueRef	The catalogue reference of the order item	String	Required
productRef	The product reference of the order item	String	Required

fulfilmentItem Definition

Property	Description	Type	Required?	Notes
skuRef	The sku reference of the fulfilment item	String	Optional
orderItemId	The order item id of the fulfilment item	String	Required	Required if skuRef is not null
rejectedQty	The rejected quantity of the fulfilment item	int	Required	Required if skuRef is not null
availableQty	The available quantity of the fulfilment item	int	Required	Required if skuRef is not null
orderItemRef	The order item reference of the fulfilment item	String	Required	Required if skuRef is not null
requestedQty	The requested quantity of the fulfilment item	int	Required	Required if skuRef is not null
fulfilmentItemRef	The fulfilment item reference	String	Required	Required if skuRef is not null

Event Request Example

1{
2  "name":"WavePack",
3  "accountId":"<accountId>",
4  "entityType":"FULFILMENT",
5  "entityId":"<fulfilmentId>",
6  "entityRef":"<fulfilmentRef>",
7  "rootEntityType":"ORDER",
8  "rootEntityId": "<orderID>",
9  "rootEntityRef": "<orderRef>",
10  "retailerId":"<retailerId>",
11  "attributes": {
12    "pickedItems": [
13      {
14        "productRef": "<productRef>",
15        "catalogueRef": "<catalogueRef>",
16        "GTIN": "<gtin>",
17        "availableQty": 1
18      }
19    ],
20    "fulfilmentItems": [
21      {
22        "skuRef": "<skuRef>",
23        "orderItemId": "<orderItemId>",
24        "rejectedQty": 0,
25        "availableQty": 1,
26        "orderItemRef": "<orderItemRef>",
27        "requestedQty": 1,
28        "fulfilmentItemRef": "<fulfilmentItemRef>"
29      }
30    ]
31  }
32}

WaveDispatchInitiated Event

This event is used externally (anything from outside this workflow) anytime finishing packing and creating an article in the store is triggered.Request Payload

Property	Description	Type	Required?
fulfilmentArticles	The list of fulfilment articles	[fulfilmentArticle]	Optional

fulfilmentArticle Definition

Property	Description	Type	Required?	Notes
name	The name of the article	String	Optional
depth	The depth of the article	String	Optional
width	The width of the article	String	Optional
height	The height of the article	String	Optional
weight	The weight of the article	String	Optional
maxWeight	The maxWeight of the article	String	Optional

Event Request Example

1{
2  "name":"WaveDispatchInitiated",
3  "accountId":"<accountId>",
4  "entityType":"FULFILMENT",
5  "entityId":"<fulfilmentId>",
6  "entityRef":"<fulfilmentRef>",
7  "rootEntityType":"ORDER",
8  "rootEntityId": "<orderID>",
9  "rootEntityRef": "<orderRef>",
10  "retailerId":"<retailerId>",
11  "attributes":{
12    "fulfilmentArticles":[
13      {
14      "name":"<name>",
15      "depth":"<depth>",
16      "width":"<width>",
17      "height":"<height>",
18      "weight":"<weight>",
19      "maxWeight":"<maxWeight>"
20      }
21    ]
22  }
23}

FulfilmentPack Event

This event is triggered by the Wave entity and starts the packing process for the items in the fulfillment.

Note

This interface contract duplicates WavePack Event. This was done to ensure backward compatibility and introduce new functionality (Pack for multi-parcel shipments).

Request Payload

Property	Description	Type	Required?
pickedItems	The list of picked items	[pickedItem]	Required
fulfilmentItems	The list of fulfilment items	[fulfilmentItem]	Optional

pickedItem Definition

Property	Description	Type	Required?	Notes
GTIN	The Global Trade Item Number (GTIN) for this Product	String	Optional
availableQty	The available quantity of order item	float	Required	availableQty should be positive
catalogueRef	The catalogue reference of the order item	String	Required
productRef	The product reference of the order item	String	Required

fulfilmentItem Definition

Property	Description	Type	Required?	Notes
skuRef	The sku reference of the fulfilment item	String	Optional
orderItemId	The order item id of the fulfilment item	String	Required	Required if skuRef is not null
rejectedQty	The rejected quantity of the fulfilment item	int	Required	Required if skuRef is not null
availableQty	The available quantity of the fulfilment item	int	Required	Required if skuRef is not null
orderItemRef	The order item reference of the fulfilment item	String	Required	Required if skuRef is not null
requestedQty	The requested quantity of the fulfilment item	int	Required	Required if skuRef is not null
fulfilmentItemRef	The fulfilment item reference	String	Required	Required if skuRef is not null

Event Request Example

1{
2  "name":"FulfilmentPack",
3  "accountId":"<accountId>",
4  "entityType":"FULFILMENT",
5  "entityId":"<fulfilmentId>",
6  "entityRef":"<fulfilmentRef>",
7  "rootEntityType":"ORDER",
8  "rootEntityId": "<orderID>",
9  "rootEntityRef": "<orderRef>",
10  "retailerId":"<retailerId>",
11  "attributes": {
12    "pickedItems": [
13      {
14        "productRef": "<productRef>",
15        "catalogueRef": "<catalogueRef>",
16        "GTIN": "<gtin>",
17        "availableQty": 1
18      }
19    ],
20    "fulfilmentItems": [
21      {
22        "skuRef": "<skuRef>",
23        "orderItemId": "<orderItemId>",
24        "rejectedQty": 0,
25        "availableQty": 1,
26        "orderItemRef": "<orderItemRef>",
27        "requestedQty": 1,
28        "fulfilmentItemRef": "<fulfilmentItemRef>"
29      }
30    ]
31  }
32}

ConfirmParcels Event

This event is used to send the details of each article packed for a single Fulfilment.Request Payload

Property	Description	Type	Required?
packedItems	Contains the list of all articles and rejections of a Fulfilment processed at the packing step	PackedItem	Required

packedItem Definition

Property	Description	Type	Required?
articles	The list of all articles of a Fulfilment processed at the packing step	[FulfilmentArticle]	Required, but array can be empty
rejections	The list of all rejections of a Fulfilment processed at the packing step	[FulfilmentItemRejection]	Required, but array can be empty

fulfilmentArticle Definition

Property	Description	Type	Required?	Notes
barcode	The barcode of the packed product	String	Optional
packaging_name	The package type that the items were packed into	String	Required	For Example: Small, Medium, Large, Custom
length	The length of the article in cm	String	Required
width	The width of the article in cm	String	Required
height	The height of the article in cm	String	Required
weight	The weight of the article in kg	String	Required
maxWeight	The maxWeight of the article	String	Optional
minWeight	The minWeight of the article	String	Optional
items	The list of the packed fulfilment items	[Item]	Optional

item Definition

Property	Description	Type	Required?
fulfilmentItemId	The id of fulfilment item	String	Required
quantity	The number of the packed fulfilment item in the article	Integer	Required

fulfilmentItemRejection Definition

Property	Description	Type	Required?
fulfilmentItemId	The id of fulfilment item	String	Required
rejectedQty	The number of the rejected fulfilment item	Integer	Required
rejectReason	The reason of the rejection	SettingValueType	Required

SettingValueType Definition

Property	Description	Type	Required?	Notes
label	The label of the reject reason	String	Required	In case of rejections at the picking stage, the default value `fc.sf.rejection Reason.outsideOfPacking` will be used.
value	The value of the reject reason	String	Required	In case of rejections at the picking stage, the default value "Rejected outside of packing" will be used.

Event Request Example

1{
2  "name": "ConfirmParcels",
3  "entityType": "FULFILMENT",
4  "entityId": "89",
5  "entityRef": "94a175b8-182d-4ba5-bf9b-f41c26b473cf",
6  "entitySubtype": "HD_PFS",
7  "rootEntityType": "ORDER",
8  "rootEntityId": "79",
9  "rootEntityRef": "HD_123_314-929-5663",
10  "retailerId": "7",
11  "attributes": {
12    "packedItems": {
13      "articles": [
14        {
15          "barcode": "4567",
16          "height": "30",
17          "length": "30",
18          "maxWeight": "9.9",
19          "minWeight": "5",
20          "packaging_name": "Medium",
21          "weight": "8",
22          "width": "30",
23          "items": [
24            {
25              "fulfilmentItemId": "140",
26              "quantity": 2
27            },
28            {
29              "fulfilmentItemId": "139",
30              "quantity": 1
31            }
32          ]
33        }
34      ],
35      "rejections": [
36        {
37          "fulfilmentItemId": "139",
38          "rejectedQty": 2,
39          "rejectReason": {
40            "label": "fc.sf.rejectionReason.damagedItem",
41            "value": "damagedItem"
42          }
43        }
44      ]
45    }
46  }
47}

HD Workflow Interface Contracts

Detailed Description

OrderAppeasement Event

OrderAddressChange Event

OrderCancel Event

OrderRevision Event

WavePack Event

WaveDispatchInitiated Event

FulfilmentPack Event

ConfirmParcels Event

Building Blocks

By Type

Helpful Resources

Quick Links