Custom Service

Custom Service is an entity that contains all the information on an offered service. It must be bound to a facility and serves as a blueprint. A Service Job is the actual instance of a Custom Service.

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

Custom Service

An example for a Custom Service would be an adjustment of a shirt by adding an initial embroidery on the collar and sleeve as it's shown in the following creation example. With the creation the custom service is available for use on tenant level. A custom service can also reference another custom service (such as when one service requires another to be done first), up to a maximum depth of 25 (A -> B -> C ... -> Y).

As Custom Services could be available (or not) in different facilities or could have differences in execution time due to different reasons, before being able to use Custom Services a Facility Custom Service Connection has to be established. This is being described in the Facility Custom Service Connection part.

Orders that are split by routing decisions are currently not supported with Custom Service. We do not recommend activating Order Split when working with Custom Services and Service Jobs.

Creating a Custom Service

Create a custom service

POST/api/customservices

Body

application/json

Desired custom service to create

tenantCustomServiceIdstring

status*CustomServiceStatus (enum)

Deprecated values: ENABLED and DISABLED, use INACTIVE and ACTIVE instead

ENABLEDDISABLEDINACTIVEACTIVE

nameLocalized*LocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

descriptionLocalizedLocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

executionTimeInMininteger

Example: 120

itemsReturnableboolean

itemsRequired*ItemsRequiredEnum (enum)

MANDATORYNONE

additionalInformationarray of AdditionalInformationForCreation (object)

customAttributesnullable object

Attributes that can be added to custom service. These attributes cannot be used within fulfillment processes, but it could be useful to have the information carried here.

Response

200201400401403

The custom service was successfully updated.

Body

application/json

createdstring (date-time)

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-time)

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

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

version*integer (int64)

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

Example: 42

tenantCustomServiceIdstring

status*CustomServiceStatus (enum)

Deprecated values: ENABLED and DISABLED, use INACTIVE and ACTIVE instead

ENABLEDDISABLEDINACTIVEACTIVE

nameLocalized*LocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

descriptionLocalizedLocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

executionTimeInMininteger

Example: 120

itemsReturnableboolean

itemsRequired*ItemsRequiredEnum (enum)

MANDATORYNONE

additionalInformationarray of AdditionalInformationForCreation (object)

customAttributesnullable object

Attributes that can be added to custom service. These attributes cannot be used within fulfillment processes, but it could be useful to have the information carried here.

Request

JavaScriptCurlPython

const response = await fetch('/api/customservices', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "nameLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "itemsRequired": "MANDATORY",
      "status": "ENABLED"
    }),
});
const data = await response.json();

Response

200201

{
  "id": "text",
  "status": "ENABLED",
  "name": "text",
  "description": "text",
  "additionalInformation": [
    {
      "id": "text",
      "name": "text",
      "description": "text"
    }
  ]
}

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/customservices' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "status": "ENABLED",
    "nameLocalized": {
      "en_US": "Shirt initials embroidery",
      "de_DE": "Hemd Initialien Bestickung"
    },
    "descriptionLocalized": {
      "en_US": "The desired initials are embroidered on the collar and sleeve.",
      "de_DE": "Die gewünschten Initialien werden am Kragen und Ärmel eingestickt."
      
    },
    "tenantCustomServiceId": "CustomerServiceId",
    "executionTimeInMin": 60,
    "itemsReturnable": false,
    "itemsRequired": "MANDATORY",
    "additionalInformation": [
      {
        "nameLocalized": {
          "en_US": "Number of threads",
          "de_DE": "Anzahl der Fäden"
        },
        "descriptionLocalized": {
          "en_US": "This value indicates how many threads should be used for the embroidery",
          "de_DE": "Dieser Wert gibt an, wie viele Fäden bei der Stickerei genutzt werden sollen"
        },
        "valueType": "NUMBER",
        "isMandatory": true
      }, 
      {
        "nameLocalized": {
          "en_US": "Color",
          "de_DE": "Farbe"
        },
        "descriptionLocalized": {
          "en_US": "Color of the embroidery",
          "de_DE": "Die Farbe der Stickerei"
        },
        "valueType": "NUMBER",
        "isMandatory": true
      }
    ],
    "customAttributes": {
      "actionId": "b1eef2b0-1d5c-4819-bddc-b562beb14838"
    }
}'

Mandatory Fields

nameLocalized

This fields sets the name if the Custom Service with it's respective translations. As of October 2023, the following locales are supported: de_DE, en_US, pl_PL, ru_RU, nl_NL, fr_FR, it_IT, nb_NO. The type is a JSON and has to be used as shown in the example above. The respective translation will be used in accordance with the locale of the client requesting the object. If the client requests a locale that has no translation, the default locale of the tenant will be used. If no default locale is set up, the locale en_US is being used.

itemsRequired

The enum itemsRequired indicates whether lineItems are needed in order to execute this Custom Service. The line items are set in the Service Job. The enum can be: MANDATORY or NONE.

status

status is an enum that indicates whether this Custom Service is enabled or disabled by using the corresponding enum: ENABLED or DISABLED.

Optional Fields

descriptionLocalized

In order to add a description about the Custom Service the field descriptionLocalized can be used. Exactly as nameLocalized translations in accordance with the supported locales can be entered as a JSON in this field.

executionTimeInMin

This field is an integer that indicates how many minutes an execution of a custom service needs.

itemsReturnable

Whether an item can be returned after it has undergone this Custom Service is indicated by this boolean.

additionalInformation

This field is an array that contains objects of type additionalInformation. The following fields are part of additionalInformation:

• nameLocalized (mandatory): name of the additional information in JSON format with it's respective translations

• descriptionLocalized (optional): description of the additional information in JSON format with it's respective translations

• valueType (mandatory): indicates whether the value of this additionalInformation is STRING, BOOLEAN, NUMBER, NOVALUE or INPUT_MULTILINE_STRING

• isMandatory (optional): this boolean indicates if this Additional Information is mandatory or not

An example can be seen in the following box:

{
  "nameLocalized": {
    "en_US": "Color",
    "de_DE": "Farbe"
  },
  "descriptionLocalized": {
    "en_US": "Color of the embroidery",
    "de_DE": "Die Farbe der Stickerei"
  },
  "valueType": "NUMBER",
  "isMandatory": true
}

customAttributes

The customAttributes field is a JSON object that carries information that might be relevant to the Custom Service. The form and content of this object is completely free, but its JSON serialized size is limited. Check out the Custom Attributes section for more details.

Updating a CustomService

Patches a custom service with the given ID

PATCH/api/customservices/{customServiceId}

Path parameters

customServiceId*string

ID of custom service you want to patch

Body

application/json

Patch set

actions*array of any of

version*integer (int64)

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

Example: 42

Response

200401403404409

custom service was found & patch-set has been applied. The patched custom service is in the body.

Body

application/json

createdstring (date-time)

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-time)

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

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

version*integer (int64)

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

Example: 42

tenantCustomServiceIdstring

status*CustomServiceStatus (enum)

Deprecated values: ENABLED and DISABLED, use INACTIVE and ACTIVE instead

ENABLEDDISABLEDINACTIVEACTIVE

nameLocalized*LocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

descriptionLocalizedLocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

executionTimeInMininteger

Example: 120

itemsReturnableboolean

itemsRequired*ItemsRequiredEnum (enum)

MANDATORYNONE

additionalInformationarray of AdditionalInformationForCreation (object)

customAttributesnullable object

Attributes that can be added to custom service. These attributes cannot be used within fulfillment processes, but it could be useful to have the information carried here.

Request

JavaScriptCurlPython

const response = await fetch('/api/customservices/{customServiceId}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "version": 42,
      "actions": [
        {
          "action": "ModifyCustomService"
        }
      ]
    }),
});
const data = await response.json();

Response

200

{
  "id": "text",
  "status": "ENABLED",
  "name": "text",
  "description": "text",
  "additionalInformation": [
    {
      "id": "text",
      "name": "text",
      "description": "text"
    }
  ]
}

curl -sSL -X PATCH 'https://your.api.fulfillmenttools.com/api/customservices' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "actions": [{
      "action": "ModifyCustomService",
      "status": "ENABLED",
      "nameLocalized":{
        "en_US": "Hemd Initialien Bestickung (italic)",
        "de_DE": "Shirt initials embroidery (kursiv)"
      },
      "descriptionLocalized":{,´
        "en_US": "The desired initials are embroidered on the collar and sleeve in an italic style..",
        "de_DE": "Die gewünschten Initialien werden am Kragen und Ärmel in kursivem Stil eingestickt."
      },
      "tenantCustomServiceId": "ChangedCustomerServiceId",
      "executionTimeInMin": 70,
      "itemsReturnable": false,
      "itemsRequired": "MANDATORY"
    }],
    "version": 42
}'

Update a Custom Service by using a PUT on the URL shown above. Enter the respective id of the Custom Service in {custom service id} . The actions array and version are both mandatory. Make sure to enter the correct version of the Custom Service you like to update. Add the desired changes to the object inside the actions array. The only field inside of the object that is mandatory is action, all other fields are optional, meaning you just need to enter those fields which you like to change.

Delete Additional Information of a Custom Service by using DELETE on the URL shown above. Replace {custom service id} with the respective ID.

Adding Additional Information to a Custom Service

Create a custom service additional information

POST/api/customservices/{customServiceId}/additionalinformation

Path parameters

customServiceId*string

ID of custom service you want to create service job for

Body

application/json

Desired custom service to create

nameLocalized*LocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

descriptionLocalizedLocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

valueType*AdditionalInformationValueType (enum)

STRINGBOOLEANNUMBERNOVALUEINPUT_MULTILINE_STRING

isMandatoryboolean

Response

200201400401403

The custom service was successfully updated.

Body

application/json

createdstring (date-time)

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-time)

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

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

version*integer (int64)

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

Example: 42

tenantCustomServiceIdstring

status*CustomServiceStatus (enum)

Deprecated values: ENABLED and DISABLED, use INACTIVE and ACTIVE instead

ENABLEDDISABLEDINACTIVEACTIVE

nameLocalized*LocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

descriptionLocalizedLocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

executionTimeInMininteger

Example: 120

itemsReturnableboolean

itemsRequired*ItemsRequiredEnum (enum)

MANDATORYNONE

additionalInformationarray of AdditionalInformationForCreation (object)

customAttributesnullable object

Attributes that can be added to custom service. These attributes cannot be used within fulfillment processes, but it could be useful to have the information carried here.

Request

JavaScriptCurlPython

const response = await fetch('/api/customservices/{customServiceId}/additionalinformation', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "nameLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "valueType": "STRING"
    }),
});
const data = await response.json();

Response

200201

{
  "id": "text",
  "status": "ENABLED",
  "name": "text",
  "description": "text",
  "additionalInformation": [
    {
      "id": "text",
      "name": "text",
      "description": "text"
    }
  ]
}

After a custom service has been created, Additional Information can be added subsequently via the following API call

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/customservices/{custom service id}/additionalInformation' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "nameLocalized": {
        "en_US": "Thread Material",
        "de_DE": "Faden Material"
      },
      "descriptionLocalized": {
        "en_US": "Material of the thread",
        "de_DE": "Material des Fadens"
      },
      "valueType": "STRING"
 }'

The fields are exactly the same as describe above in the additionalInformation paragraph Custom Service. The id of the Custom Service to which the Additional Information should be added, needs to be entered in the call at {custom service id} in the URL of the post call as shown above in the code example.

Updating Additional Information

Update a custom service additional information

PUT/api/customservices/{customServiceId}/additionalinformation/{additionalInformationId}

Path parameters

customServiceId*string

ID of custom service

additionalInformationId*string

ID of additional information you want to put

Body

application/json

Desired custom service to create

nameLocalized*LocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

descriptionLocalizedLocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

valueType*AdditionalInformationValueType (enum)

STRINGBOOLEANNUMBERNOVALUEINPUT_MULTILINE_STRING

isMandatoryboolean

Response

200201400401403

The custom service was successfully updated.

Body

application/json

createdstring (date-time)

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-time)

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

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

version*integer (int64)

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

Example: 42

tenantCustomServiceIdstring

status*CustomServiceStatus (enum)

Deprecated values: ENABLED and DISABLED, use INACTIVE and ACTIVE instead

ENABLEDDISABLEDINACTIVEACTIVE

nameLocalized*LocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

descriptionLocalizedLocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

executionTimeInMininteger

Example: 120

itemsReturnableboolean

itemsRequired*ItemsRequiredEnum (enum)

MANDATORYNONE

additionalInformationarray of AdditionalInformationForCreation (object)

customAttributesnullable object

Attributes that can be added to custom service. These attributes cannot be used within fulfillment processes, but it could be useful to have the information carried here.

Request

JavaScriptCurlPython

const response = await fetch('/api/customservices/{customServiceId}/additionalinformation/{additionalInformationId}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "nameLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "valueType": "STRING"
    }),
});
const data = await response.json();

Response

200201

{
  "id": "text",
  "status": "ENABLED",
  "name": "text",
  "description": "text",
  "additionalInformation": [
    {
      "id": "text",
      "name": "text",
      "description": "text"
    }
  ]
}

curl -sSL -X PUT 'https://your.api.fulfillmenttools.com/api/customservices/{custom service id}/additionalInformation/{additional information id}' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "nameLocalized": {
        "en_US": "Thread Material",
        "de_DE": "Faden Material"
      },
      "descriptionLocalized": {
        "en_US": "Material of the thread",
        "de_DE": "Material des Fadens"
      },
      "valueType": "STRING"
 }'

Update an Additional Information of a Custom Service by using a PUT on the URL shown above. Enter the respective id of the Custom Service in {custom service id} and Additional Service id in {additional service} in the URL.

Deleting Additional Information

Delete a custom service

DELETE/api/customservices/{customServiceId}/additionalinformation/{additionalInformationId}

Path parameters

customServiceId*string

ID of custom service

additionalInformationId*string

ID of additional information you want to delete

Response

200201400401403

The custom service was successfully updated.

Body

application/json

createdstring (date-time)

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-time)

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

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

version*integer (int64)

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

Example: 42

tenantCustomServiceIdstring

status*CustomServiceStatus (enum)

Deprecated values: ENABLED and DISABLED, use INACTIVE and ACTIVE instead

ENABLEDDISABLEDINACTIVEACTIVE

nameLocalized*LocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

descriptionLocalizedLocaleString (object)

Provides Localized values. The key is the locale, the value is the translation. See https://docs.fulfillmenttools.com/api-docs/connecting-to-fulfillmenttools/restful-api/general-topics/localization#fallback-language-mechanism

executionTimeInMininteger

Example: 120

itemsReturnableboolean

itemsRequired*ItemsRequiredEnum (enum)

MANDATORYNONE

additionalInformationarray of AdditionalInformationForCreation (object)

customAttributesnullable object

Attributes that can be added to custom service. These attributes cannot be used within fulfillment processes, but it could be useful to have the information carried here.

Request

JavaScriptCurlPython

const response = await fetch('/api/customservices/{customServiceId}/additionalinformation/{additionalInformationId}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

200201

{
  "id": "text",
  "status": "ENABLED",
  "name": "text",
  "description": "text",
  "additionalInformation": [
    {
      "id": "text",
      "name": "text",
      "description": "text"
    }
  ]
}

curl -sSL -X DELETE 'https://your.api.fulfillmenttools.com/api/customservices/{custom service id}/additionalInformation/{additional information id}' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json'

Delete an Additional Information of a Custom Service by using DELETE on the URL shown above. Replace {custom service id} and {additional information id} with the respective ids.

Facility Custom Service Connection

In order to use Custom Service, it must be bound to a facility. This is achieved by creating a Facility Custom Service Connection.

Creating a Facility Custom Service Connection

Create a facility custom service connection

POST/api/facilities/{facilityId}/customservices/{customServiceId}

Path parameters

facilityId*string

ID of facility

customServiceId*string

ID of the custom service

Body

application/json

Desired custom service connection to create/update

executionTimeInMininteger

Time in minutes the custom service takes to be executed

Example: 100

status*FacilityCustomServiceConnectionStatus (enum)

ACTIVEINACTIVE

Response

201400401403

The custom service connection was successfully created.

Body

application/json

createdstring (date-time)

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-time)

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

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

version*integer (int64)

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

Example: 42

Request

JavaScriptCurlPython

const response = await fetch('/api/facilities/{facilityId}/customservices/{customServiceId}', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "status": "ACTIVE"
    }),
});
const data = await response.json();

Response

201

{
  "id": "text",
  "status": "ACTIVE",
  "facilityRef": "text",
  "customServiceRef": "text",
  "executionTimeInMin": 0
}

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/{facilityId}/customservices/{custom service id}
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "executionTimeInMin": 80,
    "status": "ACTIVE"
}'

Create a Facility Custom Service Connection by using the call above. Replace {facilityId} with the id of the facility the custom service should be added to and {custom service id} with the id of the custom service you like to add to the facility.

Mandatory Fields

status: Indicates whether this custom service is activated for the given facility

Optional Fields

executionTimeInMin: Indicates the time in minutes needed to fulfill this custom service at this facility. If no value is entered in this field, the value of the tenant-wide Custom Service will be used.

Updating a Facility Custom Service Connection

Update a facility custom service connection

PATCH/api/facilities/{facilityId}/customservices/{customServiceId}

Path parameters

facilityId*string

ID of facility

customServiceId*string

ID of the custom service

Body

application/json

Desired custom service connection to create/update

statusFacilityCustomServiceConnectionStatus (enum)

ACTIVEINACTIVE

executionTimeInMininteger

Time in minutes the custom service takes to be executed

Example: 100

version*integer (int64)

Version of the documentSet you want to update a document of

Example: 42

Response

200400401403

The custom service connection was successfully created.

Body

application/json

createdstring (date-time)

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-time)

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

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

version*integer (int64)

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

Example: 42

Request

JavaScriptCurlPython

const response = await fetch('/api/facilities/{facilityId}/customservices/{customServiceId}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "version": 42
    }),
});
const data = await response.json();

Response

200

{
  "id": "text",
  "status": "ACTIVE",
  "facilityRef": "text",
  "customServiceRef": "text",
  "executionTimeInMin": 0
}

curl -sSL -X PATCH 'https://your.api.fulfillmenttools.com/api/{facilityId}/customservices/{custom service id}
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "executionTimeInMin": 80,
    "status": "ACTIVE"
    "version": 42
}'

Replace {facilityId} with the id of the facility the custom service should be added to and {custom service id} with the id of the custom service you like to add to the facility.

While the field version is mandatory, the other fields executionTimeInMin and status are optional and can be added as the desired update requires them to.

Deleting a Facility Custom Service Connection

Delete a facility custom service connection

DELETE/api/facilities/{facilityId}/customservices/{customServiceId}

Path parameters

facilityId*string

ID of facility

customServiceId*string

ID of the custom service

Response

200400401403

The custom service connection was successfully deleted.

Request

JavaScriptCurlPython

const response = await fetch('/api/facilities/{facilityId}/customservices/{customServiceId}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

curl -sSL -X DELETE 'https://your.api.fulfillmenttools.com/api/{facilityId}/customservices/{custom service id}
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json'

Delete an Additional Information of a Custom Service by using DELETE on the URL shown above. Replace {facilityId} and {custom service id} with the respective IDs.

Getting all Custom Services of a Given Facility

Get requested Custom service connection for a facility

GET/api/facilities/{facilityId}/customservices

Path parameters

facilityId*string

ID of facility

Query parameters

Response

200401403404

Custom service connections could be found in response body.

Body

application/json

facilityCustomServiceConnectionsarray of FacilityCustomServiceConnection (object)

totalinteger

Total number of found entities for this query

Example: 42

Request

JavaScriptCurlPython

const response = await fetch('/api/facilities/{facilityId}/customservices', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "facilityCustomServiceConnections": [
    {
      "id": "text",
      "status": "ACTIVE",
      "facilityRef": "text",
      "customServiceRef": "text",
      "executionTimeInMin": 0
    }
  ],
  "total": 42
}

curl -sSL -X GET 'https://your.api.fulfillmenttools.com/api/{facilityId}/customservices/
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json'

Get all Facility Custom Service Connections of a give facility by using the url above. Replace {facilityId} with the corresponding id of the desired facility.

Service Jobs

While Custom Service serves as a blue print, a service Job is the actual instance of a Custom Service. When a Service Job is created it will always be part of a Linked Service Jobs. A new Linked Service Jobs will be created when a Service Job is created or it will be referenced by an existing Linked Service Jobs when a Service Job Link reference is provided upon Service Job creation.

While the following passages show how service jobs can be created via API, they can also be created automatically as an outcome by an Order Routing decision analogous to Pick Jobs.

Creating a Service Job

Create a service job

POST/api/servicejobs

Body

application/json

Desired service job to create

operativeProcessRefstring

customServiceRef*string

ID of the Custom Service, the Service Job should reference.

Example: "41d43211-g5a1-gg22-a716-ba095e30ds1d"

processRefstring

ID of the Process, the Service Job belongs to.

Example: "550e8400-e29b-41d4-a716-446655440000"

facilityRef*string

ID of the Facility, the Service Job is executed in.

Example: "ba095e30-879f-11ee-b9d1-0242ac120002"

shortIdstring

Example: "KD-12-1"

lineItemsarray of ServiceJobLineItemForCreation (object)

additionalInformationarray of ServiceJobAdditionalInformationForCreation (object)

customAttributesobject

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

targetTime*string (date-time)

At which time the service job is expected to be finished.

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

tenantOrderIdstring

ID of the tenant order, the linked service jobs are part of

Example: "ocff-order-100"

serviceJobLinkRefstring

ID of the Service Job Link, the Service Job should reference.

Example: "41d43211-g5a1-gg22-a716-ba095e30ds1d"

Response

201400401403

The service job was successfully created.

Body

application/json

createdstring (date-time)

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-time)

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

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

version*integer (int64)

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

Example: 42

Request

JavaScriptCurlPython

const response = await fetch('/api/servicejobs', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "customServiceRef": "41d43211-g5a1-gg22-a716-ba095e30ds1d",
      "facilityRef": "ba095e30-879f-11ee-b9d1-0242ac120002",
      "targetTime": "2020-02-03T09:45:51.525Z"
    }),
});
const data = await response.json();

Response

201

{
  "editor": {
    "userId": "text",
    "username": "text"
  },
  "operativeProcessRef": "text",
  "id": "text",
  "name": "text",
  "description": "text",
  "lineItems": [
    {
      "id": "text"
    }
  ],
  "processRef": "text",
  "facilityRef": "text",
  "status": "OPEN",
  "nameLocalized": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "descriptionLocalized": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "executionTimeInMin": 0,
  "itemsReturnable": false,
  "itemsRequired": "MANDATORY",
  "shortId": "KD-12-1",
  "additionalInformation": [
    {
      "value": "some value"
    }
  ],
  "targetTime": "2020-02-03T09:45:51.525Z",
  "customServiceRef": "41d43211-g5a1-gg22-a716-ba095e30ds1d",
  "linkedServiceJobsRef": "41d43211-g5a1-gg22-a716-ba095e30ds1d",
  "tenantOrderId": "ocff-order-100",
  "inheritedLineItems": [
    {
      "id": "text",
      "quantity": 12,
      "scannableCodes": [
        "4012345678901"
      ],
      "article": {
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "weight": 0,
        "attributes": [
          {
            "category": "descriptive",
            "key": "%%subtitle%%",
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold",
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            }
          }
        ]
      },
      "serviceJobRef": "text"
    }
  ]
}

A service job can be created with the following call:

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/servicejobs?customServiceRef={custom service id}
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customServiceRef": "sad5622-gfd1-441v-132h-23refsfsass", 
    "processRef": "a28835b9-f81a-4f63-96a6-c7e612ebc2a3",
    "facilityRef": "8a5b283a-bcf9-4f63-132h-v93ca6ea011n3",
    "lineItems": [
      {
        "quantity": 15,
        "scannableCodes": [
          "0799439112766"
        ],
        "article": {
          "tenantArticleId": "100029-W",
          "title": "White Shirt",
          "imageUrl": "https://cdn11.bigcommerce.com/s-2fhihzl616/images/stencil/960w/products/6562/24857/Mens_White_Cotton_Shirt_MS236LS_4__24507.1645457383.jpg",
          "attributes": [
            {
              "category": "descriptive",
              "priority": 100,
              "key": "Collar Type",
              "value": "Button Down Collar"
            },
            {
              "category": "descriptive",
              "priority": 200,
              "key": "Color",
              "value": "White"
            },
            {
              "category": "descriptive",
              "priority": 300,
              "key": "Material",
              "value": "100% Organic Cotton"
            },
            {
              "category": "descriptive",
              "priority": 300,
              "key": "Size",
              "value": "M - 100"
            }
          ]
        }
      }
    ]
}'

Mandatory Fields

facilityRef

The id of the facility this Service Job should be linked to.

customServiceRef

The id of the Custom Service this Service Job references. It will the contain the following fields of the references Custom Service:

• nameLocalized

• itemsRequired

• descriptionLocalized (if existent in referenced Custom Service)

• executionTimeInMin (if existent in referenced Custom Service)

• itemsReturnable (if existent in referenced Custom Service)

• additionalInformation (if existent in referenced Custom Service)

• customAttributes (if existent in referenced Custom Service)

Note: Subsequent changes to the referenced Custom Service will not affect already created Service Jobs.

targetTime

The time at which the Service Job is expected to be finished, e.g. 2024-04-03T09:45:51.525Z

Optional Fields

lineItems

The line items that will undergo the custom service

processRef

The id of the process this Service Job should be linked to. If no process id will be given a new process with a new process id will be created

operativeProcessRef

A reference to the operative process this service job belongs to.

shortId

A short identifier, e.g. SJ-13

tenantOrderId

The tenant order id of the order this service job is part of.

serviceJobLinkRef

The id of the Service Job Link this Service Job should be added to. If this id is provided a new Service Job Link will be created and added to the nextServiceJobLinks of the referenced Service Job Link. If no reference is provided a new Linked Service Job (and Service Job Link) will be created.

Updating the status of a Service Job

Update a service job

POST/api/servicejobs/{serviceJobId}/actions

Path parameters

serviceJobId*string

ID of service job you want to update

Body

application/json

Desired change to a service job

ServiceJobActionsParameter (any of)

ServiceJobInProgressActionParameter (object)ServiceJobFinishedActionParameter (object)ServiceJobCancelledActionParameter (object)ServiceJobWaitingForInputActionParameter (object)ServiceJobObsoleteActionParameter (object)ServiceJobOpenActionParameter (object)

Response

200400401403

The service job was successfully updated.

Body

application/json

createdstring (date-time)

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-time)

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

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

version*integer (int64)

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

Example: 42

Request

JavaScriptCurlPython

const response = await fetch('/api/servicejobs/{serviceJobId}/actions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "StartServiceJob",
      "version": 0
    }),
});
const data = await response.json();

Response

200

{
  "editor": {
    "userId": "text",
    "username": "text"
  },
  "operativeProcessRef": "text",
  "id": "text",
  "name": "text",
  "description": "text",
  "lineItems": [
    {
      "id": "text"
    }
  ],
  "processRef": "text",
  "facilityRef": "text",
  "status": "OPEN",
  "nameLocalized": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "descriptionLocalized": {
    "de_DE": "Wert",
    "en_US": "Value",
    "ru_RU": "значение"
  },
  "executionTimeInMin": 0,
  "itemsReturnable": false,
  "itemsRequired": "MANDATORY",
  "shortId": "KD-12-1",
  "additionalInformation": [
    {
      "value": "some value"
    }
  ],
  "targetTime": "2020-02-03T09:45:51.525Z",
  "customServiceRef": "41d43211-g5a1-gg22-a716-ba095e30ds1d",
  "linkedServiceJobsRef": "41d43211-g5a1-gg22-a716-ba095e30ds1d",
  "tenantOrderId": "ocff-order-100",
  "inheritedLineItems": [
    {
      "id": "text",
      "quantity": 12,
      "scannableCodes": [
        "4012345678901"
      ],
      "article": {
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "weight": 0,
        "attributes": [
          {
            "category": "descriptive",
            "key": "%%subtitle%%",
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold",
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            }
          }
        ]
      },
      "serviceJobRef": "text"
    }
  ]
}

The status of a Service Job can be changed by using the following API call

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/servicejobs/{servicejobid}/actions
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "StartServiceJob",
    "version": 3,
    "additionalInformation": [
      {
        "additionalInformationRef": "{additionalInfoRef}",
        "value": "value"
      }
    ]
}'

Mandatory fields

name

The status the Service Job should be changed to. The following enums are available: StartServiceJob, FinishServiceJob, CancelServiceJob, HoldServiceJob, OpenServiceJob, ObsoleteServiceJob

version

The current version of the Service Job

Optional fields

additionalInformation

The additionalInformation you want to add to the serviceJob when changing the status. This is an array an can contain multiple additionalInformation objects. This field cannot be passed when using the ObsoleteServiceJob action.

Linked Service Jobs

A Linked Service Jobs is a virtual construct that shows the sequence and dependencies between different Service Jobs.

Service Job Links

A Linked Service Jobs consists of Service Job Links. A Service Job Link holds a reference to a Service Job and to previous Service Job Links. It also holds an array of following Service Job Links. The structure of the Service Job links within a Linked Service Jobs thus maps the sequence of related Service Jobs.

A Linked Service Jobs is automatically created when a Service Job is created. It is not possible to create a Linked Service Jobs object manually. However, it is possible to add Service Job Links to a Linked Service Job and thus customize the sequence of related ServiceJobs.

Dependencies between Service Job referenced in a Linked Service Jobs

As a Linked Service Job maps the sequence of Service Jobs, it also creates dependencies between them. The order of the Service Jobs is determined by embedding Service Job Links in ServiceJobLinks by adding them to the nextServiceJobLinks array.

Example: If a Service Job Link (referencing Service Job A) is in the nextServiceJobLinks array of another Service Job Link (referencing ServiceJob B), Service Job A, which is contained in nextServiceJobLinks, must be executed first before ServiceJob B can be started. This is ensured by the fact that the status of ServiceJob B is initially NOT_READY and only changes (automatically) to OPEN as soon as all ServiceJobs contained in the nextServiceJobLinks array have the status FINISHED, CANCELLED or OBSOLETE. At the same time a status change from NOT_READY to IN_PROGRESS, FINISHED, WAITING_FOR_INPUT is not possible.

Inherited Line Items

As mentioned before, a sequence for Service Jobs can be dictated by putting them into relation via a Linked Service Job. Line Items that undergo multiple Service Jobs in a sequence are inherited by being added to the array inheritedLineItems of the following Service Jobs.

Example: Imagine a custom tailored shirt that receives an embroidery and undergoes a quality check at the end. There are 3 Service Jobs (custom tailoring, embroidery and quality check) and 2 line items (shirt to be tailored, thread that is used for the embroidery) that are involved in this process. The first Service Job (tailoring) has 1 lineItem (shirt), the following Service Job (embroidery) has 1 line item (thread) and 1 inherited line item (shirt), the last Service Job (quality check) has no line item and 2 inherited line items (shirt, thread).

Adding a ServiceJobLink to a Linked Service Jobs

A serviceJobLink can either be added to the root level of a Linked Service Job or inside an existing serviceJobLink.

Adding a service job link to the root level:

Add a ServiceJobLink to an LinkedServiceJobs on root level

POST/api/linkedservicejobs/{linkedServiceJobsId}/servicejoblinks

Path parameters

linkedServiceJobsId*string

ID of LinkedServiceJobs you want to alter

Body

application/json

Desired ServiceJobLink to add

serviceJobRef*string

Example: "0ed803c2-fa20-48d9-9c1b-0d243937a9ad"

Response

201400401403

The ServiceJobLink was successfully added to the LinkedServiceJobs.

Body

application/json

createdstring (date-time)

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-time)

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

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

version*integer (int64)

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

Example: 42

Request

JavaScriptCurlPython

const response = await fetch('/api/linkedservicejobs/{linkedServiceJobsId}/servicejoblinks', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "serviceJobRef": "0ed803c2-fa20-48d9-9c1b-0d243937a9ad"
    }),
});
const data = await response.json();

Response

201

{
  "id": "9a14e183-ff86-4b6e-a2dc-eb4c7e312ab1",
  "processRef": "9a14e183-ff86-4b6e-a2dc-eb4c7e312ab1",
  "facilityRef": "cdb1dfc4-8361-4ba9-b3c2-33a6f2fc8d05",
  "targetTime": "2024-12-21T12:25:58.037Z",
  "includedServiceJobLinkIds": [
    "cdb1dfc4-8361-4ba9-b3c2-33a6f2fc8d05"
  ],
  "includedServiceJobRefs": [
    "cdb1dfc4-8361-4ba9-b3c2-33a6f2fc8d05"
  ],
  "status": "OPEN",
  "serviceJobLinks": [
    {
      "id": "0ed803c2-fa20-48d9-9c1b-0d243937a9ad",
      "serviceJobRef": "0ed803c2-fa20-48d9-9c1b-0d243937a9ad",
      "previousServiceJobRefs": [
        "9f197dbf-c724-469b-90f1-dc94f20b2825"
      ],
      "previousServiceJobLinkRefs": [
        "9f197dbf-c724-469b-90f1-dc94f20b2825"
      ],
      "nextServiceJobLinks": []
    }
  ],
  "operativeProcessRef": "text",
  "fullIdentifier": "240429_lorem-42"
}

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/linkedservicejobs/{linkedServiceJobId}/servicejoblinks
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "serviceJobRef": "a28835b9-f81a-4f63-96a6-c7e612ebc2a3"
  }'

Adding a service job link below an existing service job link:

Add a ServiceJobLink to an ServiceJobLInk inside the LinkedServiceJobs

POST/api/linkedservicejobs/{linkedServiceJobsId}/servicejoblinks/{serviceJobLinkId}

Path parameters

linkedServiceJobsId*string

ID of LinkedServiceJobs you want to alter

serviceJobLinkId*string

ID of ServiceJobLink you want to add the new ServiceJobLink underneath

Body

application/json

Desired ServiceJobLink to add

serviceJobRef*string

Example: "0ed803c2-fa20-48d9-9c1b-0d243937a9ad"

Response

201400401403

The ServiceJobLink was successfully added nested inside the LinkedServiceJobs.

Body

application/json

createdstring (date-time)

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-time)

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

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

version*integer (int64)

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

Example: 42

Request

JavaScriptCurlPython

const response = await fetch('/api/linkedservicejobs/{linkedServiceJobsId}/servicejoblinks/{serviceJobLinkId}', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "serviceJobRef": "0ed803c2-fa20-48d9-9c1b-0d243937a9ad"
    }),
});
const data = await response.json();

Response

201

{
  "id": "9a14e183-ff86-4b6e-a2dc-eb4c7e312ab1",
  "processRef": "9a14e183-ff86-4b6e-a2dc-eb4c7e312ab1",
  "facilityRef": "cdb1dfc4-8361-4ba9-b3c2-33a6f2fc8d05",
  "targetTime": "2024-12-21T12:25:58.037Z",
  "includedServiceJobLinkIds": [
    "cdb1dfc4-8361-4ba9-b3c2-33a6f2fc8d05"
  ],
  "includedServiceJobRefs": [
    "cdb1dfc4-8361-4ba9-b3c2-33a6f2fc8d05"
  ],
  "status": "OPEN",
  "serviceJobLinks": [
    {
      "id": "0ed803c2-fa20-48d9-9c1b-0d243937a9ad",
      "serviceJobRef": "0ed803c2-fa20-48d9-9c1b-0d243937a9ad",
      "previousServiceJobRefs": [
        "9f197dbf-c724-469b-90f1-dc94f20b2825"
      ],
      "previousServiceJobLinkRefs": [
        "9f197dbf-c724-469b-90f1-dc94f20b2825"
      ],
      "nextServiceJobLinks": []
    }
  ],
  "operativeProcessRef": "text",
  "fullIdentifier": "240429_lorem-42"
}

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/linkedservicejobs/{linkedServiceJobId}/servicejoblinks/{serviceJobLinkId}
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "serviceJobRef": "a28835b9-f81a-4f63-96a6-c7e612ebc2a3"
  }'