Custom services & bundled line items

To get more information about what a custom service is, visit the info page about custom services.

More Custom Service-API information can be found here: REST API documentation - Custom Services

More Service Job-API information can be found here: REST API documentation - Service Jobs

Custom services can be defined in the fulfillmenttools platform by the /api/customservices API and then used at order creation if a custom service connection for the target facility is available (/api/facilities/{facilityId}/customservices API). A custom service in the order will be presented as a service job in the operational process.

A service could be a shortening of pants, an engraving of a watch, or an appointment for an eye test at an optician. Furthermore, services can be combined so that one service must be executed after the other.

Create custom service

To create a custom service, use POST /api/facilities/{facilityId}/customservices. In the following example body, an engraving service is created:

{
  "status": "ENABLED",
  "nameLocalized": {
    "en_US": "Engraving Service"
  },
  "descriptionLocalized": {
    "en_US": "This service engraves a given item with a required text and a an optional font. If no font is given please use the font Comic Sans."
  },
  "executionTimeInMin": 60,
  "itemsReturnable": false,
  "itemsRequired": "MANDATORY",
  "additionalInformation": [
    {
      "nameLocalized": {
        "en_US": "Text"
      },
      "descriptionLocalized": {
        "en_US": "The text which should be used for the engraving"
      },
      "valueType": "STRING"
    },
    {
      "nameLocalized": {
        "en_US": "Font"
      },
      "descriptionLocalized": {
        "en_US": "The font which should be used for the engraving"
      },
      "valueType": "STRING",
      "isMandatory": false
    }
  ]
}

Custom service facility connection

To make a custom service available in a facility, use the POST api/facilities/{facilityId}/customservices/{customServiceId} endpoint. The following body will make the custom service with {customServiceId} in facility with {facilityId} available:

{
  "executionTimeInMin": 100,
  "status": "ACTIVE"
}

Custom service example

In this use case, we want to engrave a watch and assemble an alternative wristband. Therefore, we need to add two custom services to the order. Ensure that the custom services and facility connections are available.

Here is the body of an order with two custom services that must be done one after another:

{
  "consumer": {
    "addresses": [
      {
        "salutation": "Mr.",
        "firstName": "Test",
        "lastName": "Customer",
        "street": "Domstr.",
        "houseNumber": "20",
        "postalCode": "50668",
        "city": "Köln",
        "country": "DE"
      }
    ],
    "email": "[e-mail]"
  },
  "orderDate": "2025-03-06T17:30:00Z",
  "status": "OPEN",
  "tenantOrderId": "order-4711",
  "orderLineItems": [
    {
      "quantity": 1,
      "article": {
        "tenantArticleId": "article-id-watch",
        "title": "Watch",
        "imageUrl": "https://loremflickr.com/320/240/watch"
      }
    },
    {
      "quantity": 1,
      "article": {
        "tenantArticleId": "article-id-wristband",
        "title": "wristband",
        "imageUrl": "https://loremflickr.com/320/240/wristband"
      }
    }
  ],
  "customServices": [
    {
      "customServiceDefinition": {
        "customServiceRef": "wristband-shortening-custom-service-ref"
      },
      "articleItems": [
        {
          "tenantArticleRef": "article-id-wristband",
          "quantity": 1
        }
      ],
      "customServiceItems": [
        {
          "customServiceDefinition": {
            "customServiceRef": "engraving-custom-service-ref",
            "additionalInformation": [
              {
                "additionalInformationRef": "e233c255-d5db-4e7a-b5e6-890cf28a8c26",
                "value": "Test Customer"
              },
              {
                "additionalInformationRef": "f8665135-780f-4fa9-b441-0dd5d0b59aa6",
                "value": "My Awesome Font"
              }
            ]
          },
          "customServiceItems": [],
          "articleItems": [
            {
              "tenantArticleRef": "article-id-watch",
              "quantity": 1
            }
          ]
        }
      ]
    }
  ]
}

Some details:

• Custom service with engraving-custom-service-ref will be executed first

• Custom service with wristband-shortening-custom-service-ref get the result of engraving-custom-service-ref

• Each article item can only be present once in the customServices

Bundled items

To ensure that items are not split into different pick jobs or routed to different facilities, bundled items can be used. Items can be isBundled via the custom service concept by adding items to a custom service and defining it as bundled within the order. The line items that should be bundled must be part of the orderLineItems within the order:

"customServices": [
  {
    "customServiceDefinition": {
      "isBundled": true
    },
    "articleItems": [
      {
        "tenantArticleRef": "32168",
        "quantity": 1
      }, {
        "tenantArticleRef": "31851",
        "quantity": 1
      }
    ],
    "customServiceItems": []
  }
]