Custom services & bundled line items

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

For more details on the Custom Service API, see the REST API documentation for Custom Services.

For more details on the Service Job API, see the REST API documentation for Service Jobs.

Users can define custom services in the fulfillmenttools platform using the /api/customservices API. These services can then be used during order creation if a custom service connection for the target facility is available via the /api/facilities/{facilityId}/customservices API. A custom service in the order creates a service job in the operational process.

A custom 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 another in a sequence.

Create custom service

To create a custom service, use the POST /api/facilities/{facilityId}/customservices endpoint. The following example body creates an engraving service:

{
  "status": "ENABLED",
  "nameLocalized": {
    "en_US": "Engraving Service"
  },
  "descriptionLocalized": {
    "en_US": "This service engraves a given item with a required text and an optional font. The default font is Comic Sans if one is not specified."
  },
  "executionTimeInMin": 60,
  "itemsReturnable": false,
  "itemsRequired": "MANDATORY",
  "additionalInformation": [
    {
      "nameLocalized": {
        "en_US": "Text"
      },
      "descriptionLocalized": {
        "en_US": "The text that should be used for the engraving."
      },
      "valueType": "STRING"
    },
    {
      "nameLocalized": {
        "en_US": "Font"
      },
      "descriptionLocalized": {
        "en_US": "The font that 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 makes the custom service with the specified {customServiceId} available in the facility with {facilityId}:

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

Custom service example

This use case demonstrates how to add two sequential custom services to an order: one to engrave a watch and another to assemble an alternative wristband. This requires that the custom services and their facility connections are already available.

Below is the body of an order with two nested custom services that must be performed in sequence:

{
  "consumer": {
    "addresses": [
      {
        "salutation": "Mr.",
        "firstName": "Test",
        "lastName": "Customer",
        "street": "Domstr.",
        "houseNumber": "20",
        "postalCode": "50668",
        "city": "Köln",
        "country": "DE"
      }
    ],
    "email": "[email protected]"
  },
  "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
            }
          ]
        }
      ]
    }
  ]
}

Key aspects of this structure:

• The nested custom service with the engraving-custom-service-ref is executed first.

• The parent custom service with the wristband-shortening-custom-service-ref receives the output of the nested engraving service.

• Each article item can only be assigned to one custom service within the customServices array.

Bundled items

To ensure that items are not split into different pick jobs or routed to different facilities, items can be bundled. An item bundle is created by adding multiple items to a custom service and setting the isBundled flag to true within the order. The line items that should be bundled must be part of the orderLineItems array within the order.

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