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.

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

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.

Cancelling 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": "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.

Last updated