Handover

This article focuses on the handover process for developers. For information on the handovers in the store operations process, see the Handover article in the Operations app section.

A handover job represents the handover of an order to the consumer or shipping provider.

In addition to general information such as the order date, tenant order ID, or a reference to the corresponding facility, a handover job also carries handover-relevant information. This covers:

• Handover channel:

  • Delivery: Will be handed over to a shipping service provider

  • Pick up: Will be handed over to the end customer

• Handover job cancel reason: Can be defined if the parcel(s) weren't handed over

fulfillmentools automatically creates a handover job in the following scenarios:

• The status of the pick job changes to CLOSED, and:

  • Packing isn't active.

  • All linked service jobs associated with the pick job are FINISHED.

• The status of the linked service jobs changes to FINISHED, and:

  • Packing isn't active.

  • The related pick job is in a CLOSED status.

• The status of the pack job changes to CLOSED, and:

  • Packing is active.

  • All linked service jobs associated with the pick job are FINISHED.

• The status of the parcel changes to DONE, and:

• The related pick job is in a CLOSED status.

• deliveryChannel is SHIPPING.

For shipments processed through a custom carrier, handover job creation depends on the carrier configuration. If manualParcelHandlingActive is active, fulfillmenttools doesn't create a handover job when a pick job, linked service job, or pack job closes. Instead, creation is deferred until the parcel reaches DONE status. If manualParcelHandlingActive is deactivated, the standard triggers above apply.

Automatic versus manual handover job completion

A handover job is completed (set to status HANDED_OVER) automatically when a track-and-trace event is received from a carrier with track-and-trace enabled (if a carrier integration is in place).

It's possible to manually set a handover job to status HANDED_OVER, which triggers the handover event even before the carrier has physically scanned or picked up the parcel. In this case, the information from the handover job, such as items and quantities, is used to mark all associated line items as handed over. This ensures that line item quantities are passed correctly.

Currently, it's not possible to restrict the manual action based on user roles or permissions. As a result, users can manually trigger a handover event even before the carrier picks up the parcel.

Handover configuration

The handover configuration allows users to define rules for the handover process.

The handover configuration is available at /api/configurations/handover (see the handover configuration endpoint section for more information) and affects the whole system regardless of the user role or the facility.

In the handover configuration, you can define:

• The reasons a handover was refused

Handover refusal reasons

The refused reason configuration defines the options a user can choose when a consumer refuses a handover job, and the product is marked with the reason.

You need to add the availableRefusedReasons array. For the option to be available, active must be set to true. You can then input a refusedReasonLocalized object and set up different inputs for different languages.

Localization for reasons

The response has a refusedReason field that contains one of the locales provided by the refusedReasonLocalized object. Which exact translation was chosen depends on the locale set in the authorization token when sending the request to the GET endpoint.

If no locale was provided by the client or the locale is not available in the refusedReasonLocalized object, the answer will default to the tenant locale. If the tenant locale is also not available in the refusedReasonLocalized object, then the first key-value pair will be selected.

Handover configuration endpoints

To access the current handover configuration, use the endpoint below:

GET https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/configurations/handover

To update the current handover configuration, use the endpoint below:

Endpoint

PUT https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/configurations/handover

Request body

{
    "version": 2,
    "availableRefusedReasons": [
        {
            "active": true,
            "refusedReasonLocalized": {
                "de_DE": "Falsche farbe",
                "fr_FR": "Mauvaise couleur",
                "en_US": "Wrong color"
            }
        },
        {
            "active": false,
            "refusedReasonLocalized": {
                "de_DE": "Falsche größe",
                "fr_FR": "Mauvaise taille",
                "en_US": "Wrong size"
            }
        }
    ]
}

Response body

{
    "id": "handover",
    "version": 3,
    "availableRefusedReasons": [
        {
            "active": true,
            "refusedReasonLocalized": {
                "de_DE": "Falsche farbe",
                "fr_FR": "Mauvaise couleur",
                "en_US": "Wrong color"
            },
            "refusedReason": "Wrong color"
        },
        {
            "active": false,
            "refusedReasonLocalized": {
                "de_DE": "Falsche größe",
                "fr_FR": "Mauvaise taille",
                "en_US": "Wrong size"
            },
            "refusedReason": "Wrong size"
        }
    ],
    "created": "2025-12-04T13:54:45.549Z",
    "lastModified": "2026-03-05T09:29:16.408Z"
}

Update handover configuration

put

This part of the API is in Beta status. For details, see the API release lifecycle documentation. Updates the handover configuration for the tenant. If the configuration does not exist, it will be created.

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

HandoverConfigurationForCreate

createStandaloneHandoverJobsbooleanOptionalDeprecated

This part of the API is deprecated. For details, see the API release lifecycle documentation.

If true, a handover job will be created out of a valid routing plan. It is only possible, if no pickjob nor packjobs are used for this tenant. This is a alpha feature and might be completly replaced in the future. Please only use in communication with the FFT team.

Example: true

versionnumberRequired

Responses

200

The handover configuration was successfully updated.

application/json

HandoverConfiguration

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

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

lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2020-02-03T09:45:51.525Z

versioninteger · int64Required

The version of the document to be used in optimistic locking mechanisms.

Example: 42

createStandaloneHandoverJobsbooleanOptionalDeprecated

This part of the API is deprecated. For details, see the API release lifecycle documentation.

If true, a handover job will be created out of a valid routing plan. It is only possible, if no pickjob nor pack jobs are used for this tenant. This is a alpha feature and might be completely replaced in the future. Please only use in communication with the fulfillmenttools team.

Example: true

400

Invalid input. See response for details

application/json

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

put/api/configurations/handover

HTTPcURLJavaScriptPython

PUT /api/configurations/handover HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 106

{
  "availableRefusedReasons": [
    {
      "refusedReasonLocalized": "{ en_US: 'SomeName' }",
      "active": true
    }
  ],
  "version": 1
}

{
  "availableRefusedReasons": [
    {
      "refusedReasonLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "active": true,
      "refusedReason": "Broken Item"
    }
  ],
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}

Moving handover job line items

A handover job organizes its line items across three distinct arrays, each representing a different state in the handover process:

Array	Type	Meaning
handoverJobLineItems	HandoverLineItem[]	Items that are physically present and ready to hand over
expectedHandoverJobLineItems	ExpectedHandoverLineItem[]	Items that are expected but not yet confirmed present
missingHandoverJobLineItems	MissingHandoverJobLineItem[]	Items that have been confirmed as missing

The MOVE_HANDOVER_JOB_LINE_ITEMS action allows redistribution of line items across these arrays. Partial moves are supported. A move instruction can target fewer units than the full quantity of a source item. In that case, the source entry has its quantity reduced, and the target receives a new entry with a new identifier.

Allowed move directions

All combinations of different source and target arrays are permitted:

Source (from)	Target (to)	Notes
EXPECTED	HANDOVER
EXPECTED	MISSING
MISSING	HANDOVER
MISSING	EXPECTED	transferId and globalLineItemId aren't carried over
HANDOVER	MISSING	Quantity limit applies (see validation rules)
HANDOVER	EXPECTED	transferId and globalLineItemId aren't carried over

Moving a line item within the same array (for example, EXPECTED to EXPECTED) isn't permitted.

Effect on handover job status

The handover job status is recalculated after every move operation based on the state of expectedHandoverJobLineItems:

• If one or more expected items remain, the handover job status is set to WAITING_FOR_INPUT.

• If no expected items remain, the handover job status is set to OPEN.

Move handover endpoints

Use the endpoint below to move handover job line items:

POST https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/handoverjobs/{YOUR_HANDOVER_JOB_ID}/actions

Required permission: HANDOVERJOB_WRITE

Request body

{
  "name": "MOVE_HANDOVER_JOB_LINE_ITEMS",
  "version": 3,
  "items": [
    {
      "lineItemId": "<id-of-source-line-item>",
      "from": "EXPECTED",
      "to": "HANDOVER",
      "targetQuantity": 2
    }
  ]
}

Field	Type	Description
name	string	Must be "MOVE_HANDOVER_JOB_LINE_ITEMS"
version	number	Optimistic-locking version of the handover job
items	MoveHandoverJobLineItemsInfo[]	One or more move instructions

MoveHandoverJobLineItemsInfo fields

Field	Type	Description
lineItemId	string	Identifier of the line item to move. Must exist in the from array.
from	"EXPECTED" | "HANDOVER" | "MISSING"	Source array.
to	"EXPECTED" | "HANDOVER" | "MISSING"	Target array. Must differ from from.
targetQuantity	number	Number of units to move. Must be at least 1 and at most the available quantity.

Response

Returns the updated Handoverjob object (HTTP 200). Article titles in the response are localized based on the locale set in the request's authorization token.

Validation rules

All validation is evaluated before any mutations are applied. If multiple errors are present, they are collected and returned together.

Request-level checks

Rule	Error
items array is empty	ValidationError
version in the request doesn't match the stored entity version	VersionConflictError
Handover job status isn't OPEN or WAITING_FOR_INPUT	ValidationError
Two or more entries in items share the same lineItemId and the same to	ValidationError

Per-item checks

Rule	Error condition
targetQuantity is less than 1	Must be at least 1
from and to are identical	Source and target must differ
lineItemId does not exist in the from array	Line item not found in source
targetQuantity exceeds lineItem.quantity	Can't move more than the available quantity
Source is HANDOVER and targetQuantity exceeds quantity minus handedOverQuantity	Can't move units that have already been handed over

New line item properties

Each move instruction creates a new entry in the target array. The new entry receives a new id. The following describes which fields are carried over from the source and which are set to fixed values:

When moving to HANDOVER

Field	Value
id	New identifier
globalLineItemId	New identifier
quantity	targetQuantity
handedOverQuantity	0
status	OPEN
article, tags, stickers, scannableCodes, customAttributes	Copied from source

When moving to MISSING

Field	Value
id	New identifier
quantity	targetQuantity
article, tags, stickers, scannableCodes, customAttributes	Copied from source

The fields transferId, handedOverQuantity, globalLineItemId, and status aren't present on MissingHandoverJobLineItem and are not set.

When moving to EXPECTED

Field	Value
id	New identifier
quantity	targetQuantity
transferId	Not set (undefined)
article, tags, stickers, scannableCodes, customAttributes	Copied from source

The fields handedOverQuantity, globalLineItemId, and status are not present on ExpectedHandoverJobLineItem and are not set.

When a line item is moved to EXPECTED, the transferId from the source item is never carried over. The new entry always has transferId set to undefined, regardless of the source array.