# Handover
{% hint style="info" %}
This article focuses on the handover process for developers. For information on the handovers in the store operations process, see the [handover](https://docs.fulfillmenttools.com/documentation/apps/operations-app/handover "mention")article in the [operations-app](https://docs.fulfillmenttools.com/documentation/apps/operations-app "mention")section.
{% endhint %}
A handover job represents the handover of an order to the end consumer or shipping provider.
As well as general information like the order date, tenant order ID, or a reference to the corresponding facility, a handover job carries handover relevant information. This covers:
* **Handover channel:**
* **Delivery**: will be handed over to a shipping service provider
* **Pick up**: will it be handed over to the end customer
* **Handover job cancel reason**: Can be defined if the parcel(s) weren't handed over
A handover job is automatically created when:
* A parcel has changed to status `FINISHED` while the related pick job was in status `CLOSED`
* A pick job has changed to status `CLOSED` and there is at least one parcel of the related shipment that has the status `FINISHED`
## 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](https://docs.fulfillmenttools.com/documentation/by-pillar/store-operations/carrier-management) 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.
{% hint style="warning" %}
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 picked up the parcel.
{% endhint %}
## 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](#handover-configuration-endpoints) 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-refuse-reasons)
### Handover refuse reasons
The refused reason configuration defines the options a user can choose from if a handover job is refused by a consumer and the product is marked with the reason.
You need to add the `availableRefusedReasons` array. For the option to be available, `active` needs to 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 `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:
```http
GET https://{your-tenant-name}.api.fulfillmenttools.com/api/configurations/handover
```
To update the current handover configuration, use the endpoint below:
{% tabs %}
{% tab title="Endpoint" %}
```http
PUT https://{your-tenant-name}.api.fulfillmenttools.com/api/configurations/handover
```
{% endtab %}
{% tab title="Request body" %}
```json
{
"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"
}
}
]
}
```
{% endtab %}
{% tab title="Response body" %}
```json
{
"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"
}
```
{% endtab %}
{% endtabs %}
## Update handover configuration
> This part of the API is in Beta status. For details please check the \api-release-life-cycle documentation\.\
\
Updates the handover configuration for the tenant. If the configuration does not exist, it will be created.
```json
{"openapi":"3.0.1","info":{"title":"fulfillmenttools","version":"VERSIONLESS"},"tags":[{"description":"Endpoints to create, update and read handover configuration.","name":"Handovers Configuration (Operations)"}],"servers":[{"url":"https://{tenant}.api.fulfillmenttools.com","variables":{"tenant":{"default":"your-tenant-name"}}}],"security":[{"BearerToken":[]}],"components":{"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"HandoverConfigurationForCreate":{"additionalProperties":false,"properties":{"availableRefusedReasons":{"items":{"$ref":"#/components/schemas/AvailableRefuseReasonForCreation"},"type":"array"},"createStandaloneHandoverJobs":{"deprecated":true,"description":"This part of the API is deprecated. For details please check the api-release-life-cycle 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.","type":"boolean"},"version":{"type":"number"}},"required":["version"],"type":"object","title":"HandoverConfigurationForCreate","description":"HandoverConfigurationForCreate"},"AvailableRefuseReasonForCreation":{"additionalProperties":false,"properties":{"refusedReasonLocalized":{"$ref":"#/components/schemas/LocaleString","description":"Localized reason"},"active":{"type":"boolean"}},"required":["active","refusedReasonLocalized"],"title":"AvailableRefuseReasonForCreation","description":"AvailableRefuseReasonForCreation"},"LocaleString":{"additionalProperties":{"type":"string"},"description":"Provides Localized values. The key is the locale, the value is the translation. https://docs.fulfillmenttools.com/documentation/developer-docs/api/core-concepts/localization","title":"LocaleString","type":"object"},"HandoverConfiguration":{"allOf":[{"$ref":"#/components/schemas/VersionedResource"}],"properties":{"availableRefusedReasons":{"items":{"$ref":"#/components/schemas/AvailableRefusedReason"},"type":"array"},"createStandaloneHandoverJobs":{"deprecated":true,"description":"This part of the API is deprecated. For details please check the api-release-life-cycle 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.","type":"boolean"}},"type":"object","title":"HandoverConfiguration","description":"HandoverConfiguration"},"VersionedResource":{"properties":{"created":{"description":"The date this entity was created at the platform. This value is generated by the service.","format":"date-time","type":"string"},"lastModified":{"description":"The date this entity was modified last. This value is generated by the service.","format":"date-time","type":"string"},"version":{"description":"The version of the document to be used in optimistic locking mechanisms.","format":"int64","type":"integer"}},"required":["version"],"type":"object","title":"VersionedResource","description":"VersionedResource"},"AvailableRefusedReason":{"additionalProperties":false,"properties":{"refusedReasonLocalized":{"$ref":"#/components/schemas/LocaleString"},"active":{"type":"boolean"},"refusedReason":{"description":"translated refusedReason selected from refusedReasonLocalized","type":"string"}},"required":["refusedReasonLocalized","active"],"title":"AvailableRefusedReason","description":"AvailableRefusedReason"},"ApiError":{"items":{"$ref":"#/components/schemas/ErrorInner"},"type":"array","xml":{"name":"ApiError"},"title":"ApiError","description":"ApiError"},"ErrorInner":{"properties":{"description":{"type":"string"},"requestVersion":{"description":"The version provided within an invalid request.","format":"int64","type":"integer"},"summary":{"type":"string"},"version":{"format":"int64","type":"integer"}},"required":["summary"],"type":"object","title":"ErrorInner","description":"ErrorInner"}}},"paths":{"/api/configurations/handover":{"put":{"description":"This part of the API is in Beta status. For details please check the api-release-life-cycle documentation.
Updates the handover configuration for the tenant. If the configuration does not exist, it will be created.","operationId":"upsertHandoverConfiguration","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandoverConfigurationForCreate"}}},"description":"Desired HandoverConfiguration","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandoverConfiguration"}}},"description":"The handover configuration was successfully updated."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"description":"Invalid input. See response for details"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"description":"Your user is not allowed to operate against this API instance"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"description":"Your user, although recognized, is not authorized to use this endpoint"}},"summary":"Update handover configuration","tags":["Handovers Configuration (Operations)"]}}}}
```