Handover Jobs

A handover job represents the handover of an order to the end consumer or parcel service provider and provides all the necessary information.

This page is outdated. Please go to our new documentation under https://docs.fulfillmenttools.com/documentation.

Despite general information like the order date, tenant order id or a reference to the corresponding facility a handover job carries handover relevant information like the handover channel (DELIVERY: will it be handed over to a parcel service provider or COLLECT: will it be handed over to the end customer) or handover job cancel reason (it was not handed over due to a no show of the customer, the order was cancelled, etc.).

Creating a Handover Job

A handover will automatically created when a parcel has changed to status FINISHED while the related Pick Job was in status CLOSED or a pick job has changed to status CLOSED and there is at least one Parcel of the related Shipment that is in status FINISHED.

Alternatively a Handover Job can be created via REST Api

Add a new handoverjob

post

Authorizations

Body

carrierLogoUrlstringoptional

The URL to the carrier logo

carrierRefstringoptional

carrierTrackingNumberstringoptional

Tracking number for the created shipment

channelstring · enumrequired

Available options:

customAttributesobjectoptional

Attributes that can be added to the handover job. These attributes cannot be used within fulfillment processes, but it could be useful to have the informations carried here.

facilityRefstringrequired

The id of the facility reference.

Example: Esb20gpHBL94X5NdMp3C

handoverJobLineItemsobject[]optional

loadUnitRefsstring[]optional

Reference to array of load unit Refs

orderDatestring · date-timerequired

The date this order was created at the supplying system.

Example: 2020-02-03T08:45:50.525Z

parcelRefstringoptional

The reference to the parcel.

Example: 2fOge2ZGW54K4TgvDTQw

pickJobRefstringoptional

The reference to the pickjob for which the handoverjob is assigned to

Example: ca525716-7208-4a63-a2a6-11274eb37f67-0

processIdstringoptional

Id of the global process related to this entity. For example used for starting the GDPR process and others.

shipmentRefstringoptional

The reference to the shipment belonging to the handoverjob

Example: Esb20gpHBL94X5NdMp3C

shortIdentifierstringoptional

The short identifier of the shipment.

statusstring · enumoptional

Available options:

targetTimestring · date-timerequired

The time the handoverjob is expected to be picked up at the facility.

tenantOrderIdstringoptional

Field can be used as a reference number in foreign systems, for example as a reference to the source system's identifier for this order.

Example: R456728546

paidbooleanoptional

Indicates if the order is already paid

Example: false

tagsobject[] · min: 1optional

Tags can only be set when there is no process related with this handoverJob. Setting processId and tags will lead to an validationError.

stickersobject[] · min: 1optional

cancelReasonstring · enumoptional

Available options:

invoiceAddressall ofoptional

recipientAddressall ofoptional

fullIdentifierstringoptional

An information to identify the recipient

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://%%HOST%%//api/handoverjobs' \
  --header 'Content-Type: application/json' \
  --data '{
    "carrierLogoUrl": "text",
    "carrierRef": "text",
    "carrierTrackingNumber": "text",
    "channel": "DELIVERY",
    "customAttributes": {},
    "facilityRef": "Esb20gpHBL94X5NdMp3C",
    "handoverJobLineItems": [
      {
        "article": {
          "customAttributes": {},
          "imageUrl": "text",
          "tenantArticleId": "4711",
          "title": "Cologne Water",
          "weight": 1,
          "attributes": [
            {
              "category": "descriptive",
              "key": "%%subtitle%%",
              "priority": 100,
              "value": "585er Gold"
            }
          ]
        },
        "picked": 20,
        "quantity": 21,
        "substituteLineItems": [
          {
            "article": {
              "customAttributes": {},
              "imageUrl": "text",
              "tenantArticleId": "4711",
              "title": "Cologne Water",
              "weight": 1,
              "attributes": [
                {
                  "category": "descriptive",
                  "key": "%%subtitle%%",
                  "priority": 100,
                  "value": "585er Gold"
                }
              ]
            },
            "priority": 1,
            "quantity": 21,
            "scannableCodes": [
              "text"
            ],
            "partialStockLocations": [
              {
                "quantity": 21,
                "location": {
                  "locationRef": "text",
                  "scannableCodes": [
                    "text"
                  ]
                }
              }
            ]
          }
        ],
        "tags": [],
        "stickers": []
      }
    ],
    "loadUnitRefs": [
      "text"
    ],
    "orderDate": "2020-02-03T08:45:50.525Z",
    "parcelRef": "2fOge2ZGW54K4TgvDTQw",
    "pickJobRef": "ca525716-7208-4a63-a2a6-11274eb37f67-0",
    "processId": "text",
    "shipmentRef": "Esb20gpHBL94X5NdMp3C",
    "shortIdentifier": "text",
    "status": "OPEN",
    "targetTime": "2025-04-01T01:00:26.902Z",
    "tenantOrderId": "R456728546",
    "paid": false,
    "tags": [],
    "stickers": [],
    "cancelReason": "CONSUMER_NO_SHOW",
    "invoiceAddress": {
      "companyName": "Speedy Boxales Ltd.",
      "firstName": "Maxine",
      "lastName": "Muller",
      "salutation": "Frau",
      "email": "[e-mail]",
      "addressType": "POSTAL_ADDRESS",
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "province": "NRW",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "street": "Hauptstr."
    },
    "recipientAddress": {
      "companyName": "Speedy Boxales Ltd.",
      "firstName": "Maxine",
      "lastName": "Muller",
      "salutation": "Frau",
      "email": "[e-mail]",
      "addressType": "POSTAL_ADDRESS",
      "additionalAddressInfo": "to care of: Mrs. Müller",
      "city": "Langenfeld",
      "country": "DE",
      "province": "NRW",
      "customAttributes": {},
      "houseNumber": "42a",
      "phoneNumbers": [
        {
          "customAttributes": {},
          "label": "text",
          "type": "MOBILE",
          "value": "text"
        }
      ],
      "postalCode": "40764",
      "street": "Hauptstr."
    },
    "fullIdentifier": "text"
  }'

201

400

401

403

201

{
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42,
  "carrierLogoUrl": "text",
  "carrierRef": "text",
  "carrierTrackingNumber": "text",
  "channel": "DELIVERY",
  "customAttributes": {},
  "facilityRef": "Esb20gpHBL94X5NdMp3C",
  "handoverJobLineItems": [
    {
      "article": {
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1,
        "attributes": [
          {
            "category": "descriptive",
            "key": "%%subtitle%%",
            "priority": 100,
            "value": "585er Gold"
          }
        ]
      },
      "picked": 20,
      "quantity": 21,
      "substituteLineItems": [
        {
          "article": {
            "customAttributes": {},
            "imageUrl": "text",
            "tenantArticleId": "4711",
            "title": "Cologne Water",
            "weight": 1,
            "attributes": [
              {
                "category": "descriptive",
                "key": "%%subtitle%%",
                "priority": 100,
                "value": "585er Gold"
              }
            ]
          },
          "priority": 1,
          "quantity": 21,
          "scannableCodes": [
            "text"
          ],
          "partialStockLocations": [
            {
              "quantity": 21,
              "location": {
                "locationRef": "text",
                "scannableCodes": [
                  "text"
                ]
              }
            }
          ]
        }
      ],
      "tags": [],
      "stickers": []
    }
  ],
  "loadUnitRefs": [
    "text"
  ],
  "orderDate": "2020-02-03T08:45:50.525Z",
  "parcelRef": "2fOge2ZGW54K4TgvDTQw",
  "pickJobRef": "ca525716-7208-4a63-a2a6-11274eb37f67-0",
  "processId": "text",
  "shipmentRef": "Esb20gpHBL94X5NdMp3C",
  "shortIdentifier": "text",
  "status": "OPEN",
  "targetTime": "2025-04-01T01:00:26.902Z",
  "tenantOrderId": "R456728546",
  "paid": false,
  "tags": [],
  "stickers": [],
  "cancelReason": "CONSUMER_NO_SHOW",
  "invoiceAddress": {
    "companyName": "Speedy Boxales Ltd.",
    "firstName": "Maxine",
    "lastName": "Muller",
    "salutation": "Frau",
    "email": "[e-mail]",
    "addressType": "POSTAL_ADDRESS",
    "additionalAddressInfo": "to care of: Mrs. Müller",
    "city": "Langenfeld",
    "country": "DE",
    "province": "NRW",
    "customAttributes": {},
    "houseNumber": "42a",
    "phoneNumbers": [
      {
        "customAttributes": {},
        "label": "text",
        "type": "MOBILE",
        "value": "text"
      }
    ],
    "postalCode": "40764",
    "street": "Hauptstr."
  },
  "recipientAddress": {
    "companyName": "Speedy Boxales Ltd.",
    "firstName": "Maxine",
    "lastName": "Muller",
    "salutation": "Frau",
    "email": "[e-mail]",
    "addressType": "POSTAL_ADDRESS",
    "additionalAddressInfo": "to care of: Mrs. Müller",
    "city": "Langenfeld",
    "country": "DE",
    "province": "NRW",
    "customAttributes": {},
    "houseNumber": "42a",
    "phoneNumbers": [
      {
        "customAttributes": {},
        "label": "text",
        "type": "MOBILE",
        "value": "text"
      }
    ],
    "postalCode": "40764",
    "street": "Hauptstr."
  },
  "fullIdentifier": "text",
  "anonymized": false,
  "id": "95EWrieX09OmeriXIUbb",
  "documents": [
    {
      "id": "text",
      "documentType": "PDF",
      "documentCategory": "EXTERNAL",
      "status": "AVAILABLE",
      "operations": [
        "PRINT"
      ],
      "name": "text",
      "path": "text",
      "priority": 1
    }
  ],
  "documentsRef": "text",
  "carrierKey": "text"
}

The handoverjob was successfully created. The Location header contains the URL of it.

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/handoverjobs' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "carrierRef": "d802fcce-42ac-0f1s-d311-e6f97687353a",
    "channel": "DELIVERY",
    "facilityRef": "f92fcec6-dc65-4532-af40-e057683ad873",
    "handoverJobLineItems": [
        {
            "article": {
                "customAttributes": {},
                "imageUrl": "string",
                "tenantArticleId": "4711",
                "title": "Cologne Water",
                "weight": 10,
                "attributes": [
                    {
                        "category": "descriptive",
                        "key": "%%subtitle%%",
                        "priority": 100,
                        "value": "585er Gold"
                    }
                ]
            },
            "quantity": 21,
            "handedOverQuantity": 20,
            "substituteLineItems": [
                {
                    "article": {
                        "customAttributes": {},
                        "imageUrl": "string",
                        "tenantArticleId": "4711",
                        "title": "Cologne Water",
                        "weight": 0,
                        "attributes": []
                    },
                    "priority": 0,
                    "quantity": 21,
                    "handedOverQuantity": 20,
                    "scannableCodes": [
                        "978020137962"
                    ],
                    "partialStockLocations": [
                        {
                            "quantity": 21,
                            "location": {
                                "locationRef": "string",
                                "scannableCodes": [
                                    "978064813962"
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    ],
    "orderDate": "2023-07-08T08:45:50.525Z",
    "pickJobRef": "ccf150a3-91a7-4c16-a301-f246ef2db6c6",
    "processId": "49609d17-e26c-487f-8f2c-86ddc02e0863",
    "shipmentRef": "be67a593-fad7-4250-be61-7a3cc87820ea",
    "shortIdentifier": "SH31",
    "status": "OPEN",
    "targetTime": "2023-07-06T08:03:36.197Z",
    "tenantOrderId": "R456728546",
    "paid": false,
    "cancelReason": "CONSUMER_NO_SHOW",
    "invoiceAddress": {
        "street": "Schanzenstr.",
        "houseNumber": "30",
        "postalCode": "51063",
        "city": "Köln",
        "country": "DE",
        "phoneNumbers": [
            {
                "value": "0177-555-6273",
                "label": "private",
                "type": "MOBILE"
            }
        ],
        "additionalAddressInfo": "3. Etage",
        "salutation": "Herr",
        "firstName": "Homer",
        "lastName": "Simpson",
        "addressType": "POSTAL_ADDRESS"
    },
    "recipientAddress": {
        "street": "Schanzenstr.",
        "houseNumber": "30",
        "postalCode": "51063",
        "city": "Köln",
        "country": "DE",
        "phoneNumbers": [
            {
                "value": "0177-555-6273",
                "label": "private",
                "type": "MOBILE"
            }
        ],
        "additionalAddressInfo": "3. Etage",
        "salutation": "Herr",
        "firstName": "Homer",
        "lastName": "Simpson",
        "addressType": "POSTAL_ADDRESS"
    },
}
'

Mandatory Fields

channel

The channel describes whether this order will be collected by the customer or by a parcel service provider. The value can either be COLLECT or DELIVERY

facilityRef

The id of the facility this order is handed over in

orderDate

The date and time this order was placed

targetTime

The date and time this handover job has to be handed over

Optional Fields

carrierLogoUrl

The url to the logo of the carrier for displaying purposes in the Backoffice

carrierRef

The id of the carrier in case this is an order fulfilled by a parcel service provider

carrierTrackingNumber

The tracking number provided by the parcel service provider.

customAttributes

Additional information you might want to add to this Handover Job.

handoverJobLineItems

The items that the Handover Job contains.

loadUnitRefs

The ids of the Load Units used in the picking process of this order.

parcelRef

The id of the Parcel used

pickJobRef

The id of the related Pick Job

processId

The id of the related Process

operativeProcessRef

The id of the related Operative Process

shipmentRef

The id of the related shipment.

shortIdentifier

A short id

status

The status of the Handover Job it should be created in. Can be: OPEN, HANDED_OVER, OBSOLETE, CANCELED (created in OPEN when not provided)

tenantOrderId

The id you use internally for this order.

paid

A boolean flag that indicates whether this order has already been paid for or not

tags

The tags that are related to this Handover Job

stickers

Stickers that are related to this Handover Job.

cancelReason

The reason this hand over has been cancelled. Can be: CONSUMER_NO_SHOW, CONSUMER_REJECTS, ORDER_CANCELLED

invoiceAddress

Address of the invoice.

recipientAddress

Address of the recipient.

fullIdentifier

A longer identifier

transfers

Transfers related to this Handover Job.

Finishing a Handover Job

Call a single action on a given Handover job

post

Authorizations

Path parameters

handoverJobIdstringrequired

Reference to the handover job you want to call the action for

Body

any ofoptional

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://%%HOST%%//api/handoverjobs/{handoverJobId}/actions' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "CANCEL",
    "version": 1,
    "payload": {
      "handoverJobCancelReason": "CONSUMER_NO_SHOW"
    }
  }'

200

401

403

200

{
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42,
  "carrierLogoUrl": "text",
  "carrierRef": "text",
  "carrierTrackingNumber": "text",
  "channel": "DELIVERY",
  "customAttributes": {},
  "facilityRef": "Esb20gpHBL94X5NdMp3C",
  "handoverJobLineItems": [
    {
      "article": {
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1,
        "attributes": [
          {
            "category": "descriptive",
            "key": "%%subtitle%%",
            "priority": 100,
            "value": "585er Gold"
          }
        ]
      },
      "picked": 20,
      "quantity": 21,
      "substituteLineItems": [
        {
          "article": {
            "customAttributes": {},
            "imageUrl": "text",
            "tenantArticleId": "4711",
            "title": "Cologne Water",
            "weight": 1,
            "attributes": [
              {
                "category": "descriptive",
                "key": "%%subtitle%%",
                "priority": 100,
                "value": "585er Gold"
              }
            ]
          },
          "priority": 1,
          "quantity": 21,
          "scannableCodes": [
            "text"
          ],
          "partialStockLocations": [
            {
              "quantity": 21,
              "location": {
                "locationRef": "text",
                "scannableCodes": [
                  "text"
                ]
              }
            }
          ]
        }
      ],
      "tags": [],
      "stickers": []
    }
  ],
  "loadUnitRefs": [
    "text"
  ],
  "orderDate": "2020-02-03T08:45:50.525Z",
  "parcelRef": "2fOge2ZGW54K4TgvDTQw",
  "pickJobRef": "ca525716-7208-4a63-a2a6-11274eb37f67-0",
  "processId": "text",
  "shipmentRef": "Esb20gpHBL94X5NdMp3C",
  "shortIdentifier": "text",
  "status": "OPEN",
  "targetTime": "2025-04-01T01:00:26.902Z",
  "tenantOrderId": "R456728546",
  "paid": false,
  "tags": [],
  "stickers": [],
  "cancelReason": "CONSUMER_NO_SHOW",
  "invoiceAddress": {
    "companyName": "Speedy Boxales Ltd.",
    "firstName": "Maxine",
    "lastName": "Muller",
    "salutation": "Frau",
    "email": "[e-mail]",
    "addressType": "POSTAL_ADDRESS",
    "additionalAddressInfo": "to care of: Mrs. Müller",
    "city": "Langenfeld",
    "country": "DE",
    "province": "NRW",
    "customAttributes": {},
    "houseNumber": "42a",
    "phoneNumbers": [
      {
        "customAttributes": {},
        "label": "text",
        "type": "MOBILE",
        "value": "text"
      }
    ],
    "postalCode": "40764",
    "street": "Hauptstr."
  },
  "recipientAddress": {
    "companyName": "Speedy Boxales Ltd.",
    "firstName": "Maxine",
    "lastName": "Muller",
    "salutation": "Frau",
    "email": "[e-mail]",
    "addressType": "POSTAL_ADDRESS",
    "additionalAddressInfo": "to care of: Mrs. Müller",
    "city": "Langenfeld",
    "country": "DE",
    "province": "NRW",
    "customAttributes": {},
    "houseNumber": "42a",
    "phoneNumbers": [
      {
        "customAttributes": {},
        "label": "text",
        "type": "MOBILE",
        "value": "text"
      }
    ],
    "postalCode": "40764",
    "street": "Hauptstr."
  },
  "fullIdentifier": "text",
  "anonymized": false,
  "id": "95EWrieX09OmeriXIUbb",
  "documents": [
    {
      "id": "text",
      "documentType": "PDF",
      "documentCategory": "EXTERNAL",
      "status": "AVAILABLE",
      "operations": [
        "PRINT"
      ],
      "name": "text",
      "path": "text",
      "priority": 1
    }
  ],
  "documentsRef": "text",
  "carrierKey": "text"
}

Updated Handover job in the body.

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/handoverjobs/HANDOVER-JOB-ID/actions/' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "FINISH_HANDOVER_JOB",
    "version": 7,
    "lineItems": [
      {
        "id": "58b8cfa6-c36c-46fb-a6fb-f0fa32228c01",
        "handedOverQuantity": 100,
      }
    ]
}'

Optional Fields

lineItems

lineItems that have (not) been handed over. You can pass an array of line items that have been handed over (or not) including substitute items and add information about items that have been refused (by the customer).

Cancelling a Handover Job

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/handoverjobs/HANDOVER-JOB-ID/actions/' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "CANCEL",
    "version": 7,
}'

Setting refused reasons for a Handover Job

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/handoverjobs' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "UPDATE_LINEITEM",
    "version": 7,
    "lineItem": {
      "id": "a1b993cd-073f-487f-ac48-52fac9a97b65",
      "refused": [
        {
          "quantity": 1,
          "reasonLocalized": {
            "de_DE": "kaputt",
            "en_US": "broken"
          }
        }
      ]
    }
}'

While you can configure available refused reasons via the Handover Job Configuration, the reasons that are passed with this request will not be validated against those that have been configured. This gives you the flexibility between having e.g. free forms for the refused reasons as well as providing pre-defined ones for your clients.

Passing no reason is not allowed. To pass no reasons an appropriate reason (e.g. 'No Reasons') should be used.